Conroller SpecからREST APIの利用例を自動生成するGemを作ってみた

Ruby Rails

最近、スマホからRESTでアクセスしてデータ取ってくるシステムのサーバーサイドを作ることが多いのですが、API仕様書書いてくれと言われて面倒になったので、なんとかしたかった。
そこで、そもそもRESTの入力と出力の仕様って、controllerのspecを書いていればそこに書いてあって出力も取れるので、それを整形してmarkdownにすりゃ大体OKじゃないかと思ったので、controllerのspecを流すついでに自動生成するようなGemを作りました。
Rubyistでない人にソース読んでくれ、とは言えないし。


joker1007/ghost_writer · GitHub


なんかGemっぽいキラキラネームにしようと思って、それっぽい名前を付けましたが、相変わらず中身はしょぼいです。特に出力周りがw
後、rpsec-railsに依存しているので、railsじゃないと使えない。



使い方は、こんな感じ。

RSpec.configure do |config|
  config.include GhostWriter
  config.after(:suite) do # 2013/1/17 追記
    GhostWriter.generate_api_doc
  end
end

require 'spec_helper'

describe PostsController do
  describe "GET index" do
    it "should be success", generate_api_doc: true do # Add metadata :generate_api_doc
      get :index
      response.should be_success
    end

    it "should be success", generate_api_doc: "index_error" do # if metadata value is string, use it as filename
      get :index
      response.status.should eq 404
    end
  end
end


ただ、これだけだと出力されない。
出力がテストデータに依存しているため、idのように実行時にころころ変わるような値が出力にも影響してしまうので、rspec実行時に環境変数を渡さないと出力されないようになってます。

GENERATE_API_DOC=1 bundle exec rake spec


元々は、formatterでやれるかと思ったんですが、rspecのソース読んだ所、exampleを実行したらexample_group_instanceがクリアされて、メタデータとかテストケース内で使ったデータとかにアクセスできなかったりで、こんな形に。


なんか、専用のcliインターフェース作って、ドキュメント生成っぽくした方がいいかもしれない。
今の所、markdownで出力するだけだが、出力フォーマットを多少選べるようにするのもありかもしれない。


相変わらず、テストコード書くのが辛かった・・・。
rspec-coreとrspec-railsのテストコードを参考にspec内でspec流すテストを調べたりとか。