sinatraでautodoc

APIのドキュメンテーション

今更ながらSinatraを使ったことがなかったのでWebAPIを書いてみた。
シンプルで使いやすかったです。

で、READMEをはじめ良いドキュメントがついてると良いプロダクトな気配を感じるので、
APIドキュメンテーションに挑戦。

調査

• アノテーション不要 -> 5分で面倒くさくなる自信がある。複数人で開発すると質がバラける
• Sinatraでつかえる -> RailsApp限定のものもちらほら
• できればGithubで簡潔 -> あれこれ見るのは面倒臭い

が希望。
APIドキュメントを書くのが楽になるツールまとめ - Qiita
などを参考に試してみて、最終的にAUTODOCに決定

AUTODOC

7kamuraさんが公開されているgemで、テストベースでドキュメントを自動生成してくれます。

Rack applicationで実装されたAPIに対して、RSpecで書かれたテストを元にAPIドキュメントを生成するもの。 テストを実行すると、テスト中に発行したリクエストやレスポンス、そのテストに付けられたメッセージを元に、 良い感じに情報をまとめ、Markdown形式でAPIドキュメントを記したファイルを生成してくれる。

( ﾟДﾟ)ｳﾋｮｰ

利用開始＆例外

gem入れて、metadataにautodoc: true入れて、

diff --git spec/requests/hello_api_spec.rb spec/requests/hello_api_spec.rb
index 1a7698f..d24a3a1 100644
--- spec/requests/hello_api_spec.rb
+++ spec/requests/hello_api_spec.rb
@@ -12,7 +12,7 @@ describe 'hello API' do
       get entry_point
     end

-    it 'hello :)' do
+    it 'hello :)', autodoc: true do
       expect(json).to eq({'message' => 'hello :)'})
     end
   end
diff --git spec/spec_helper.rb spec/spec_helper.rb
index 88ecf8a..51b7545 100644
--- spec/spec_helper.rb
+++ spec/spec_helper.rb
@@ -3,6 +3,7 @@ require 'rspec'
 require 'rack/test'
 require 'json'

+require 'autodoc'

 require_relative '../app'

AUTODOC=1入れてGuardを実行

$ AUTODOC=1 RACK_ENV=development bundle exec guard

/path/to/project/vendor/bundle/ruby/2.1.0/gems/actionpack-4.2.1/lib/action_dispatch/http/mime_negotiation.rb:6:in `<module:MimeNegotiation>': uninitialized constant ActiveSupport::Concern (NameError)

OH...

解決策

diff --git spec/spec_helper.rb spec/spec_helper.rb
index 51b7545..cb358e3 100644
--- spec/spec_helper.rb
+++ spec/spec_helper.rb
@@ -3,6 +3,7 @@ require 'rspec'
 require 'rack/test'
 require 'json'

+require 'active_support/core_ext/module/concerning'
 require 'autodoc'

 require_relative '../app'

無いならrequireしてやればよい。

できたもの

サンプルプロジェクト
https://github.com/kotatsu360/autodoc-using-sinatra
ドキュメント
https://github.com/kotatsu360/autodoc-using-sinatra/blob/master/doc/hello_api.md

autodocの中でrequestsというディレクトリを期待しているので、
APIのspecはそこに置いている。rails的なお約束なんだろうか。

調査中

• RailsAppだとどうなのか
• module concernで調べると3ファイルくらいあるけどどれがいいのか

不具合なのか使い方が悪いのか調査中