最近、スマホから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流すテストを調べたりとか。