Test::JsonAPI::Autodocをリリースしました
Test::JsonAPI::Autodocをリリースしました．
https://metacpan.org/pod/Test::JsonAPI::Autodoc
https://github.com/moznion/Test-JsonAPI-Autodoc
これは何
Ruby (RSpec) にはautodocという，@r7kamuraさんが書かれたクールなモジュールがあって，
これが何かと言うと，JSON APIのテストを記述するとそのリクエストとレスポンスに応じて
自動的にそのAPIのドキュメントを生成してくれるという大層便利なモジュールです．
「テストを書くとドキュメントが出来る」という発想は最早発明と言っても過言では無いでしょう．
autodocにまつわる情報は以下を参照頂いた方が詳しくて良いでしょう．
- r7kamura/autodoc
- 体育の日って高速に唱えるとテストの日に聴こえる - ✘╹◡╹✘
- Rails でつくる API のドキュメントを自動生成してくれる autodoc がすごい - 彼女からは、おいちゃんと呼ばれています
で，これにインスパイアされて……というかこのアイデアをパクって出来たのが
このTest::JsonAPI::Autodocです．
使い方
大体ドキュメントに書いてある通りです．
こんな感じで，Test::JsonAPI::Autodocを使ったテストを書いてやって……
$ TEST_JSONAPI_AUTODOC=1 prove t/test_jsonapi_autodoc.t
という感じでテストを走らせてやると，
(ちなみに，TEST_JSONAPI_AUTODOCという環境変数に真値を入れない場合はドキュメントが生成されません)
このようなMarkdown形式のドキュメントが生成されます．便利っぽい！
ちょっと詳しく
describeというメソッドはsubtestと同じような使い方が可能なメソッドで *1，
このdescribeメソッドの内部でhttp_okメソッドを呼び出してやると，
http_okメソッドがAPIのテストを行って (APIのテストと言ってもステータスコードを見るだけですが)，
その後にリクエストとレスポンスに応じてMarkdown形式のドキュメントを自動的に生成します．
なお，describeメソッドの第一引数の文字列はドキュメントの見出しに，
http_okメソッドの第三引数の文字列はドキュメントの説明 (見出しの下のノート) になります．
http_okメソッドは単体で利用する事も可能ですが (つまり，describeメソッドの外部で呼び出す)，
その場合はステータスコードのチェックを行うだけで，ドキュメントの生成は行いません．
Markdownドキュメントは，デフォルトではプロジェクトルート直下のdocs/test_name.mdというパスに出力されます．
ドキュメントの出力先はset_documents_pathというメソッドで設定してやることが出来ます．
なお，ここでいう「プロジェクトルート」とはテストスクリプトからルートディレクトリに遡る途中で発見した
cpanfileが置いてあるディレクトリの事を指します．つまりcpanfileをどこか *2 に配置してやる必要があります
また，生成されるMarkdownのテンプレートも，set_templateというメソッドで自由にカスタムすることが出来ます．
これに関してはドキュメントを参照して下さい．
https://metacpan.org/pod/Test::JsonAPI::Autodoc#CUSTOM-TEMPLATE
こんな感じです！！！
なんか便利そうなので是非ご利用下さいませ．
多分，まだ色々至らない部分があると思うので，皆様のフィードバックをお待ちしております．
追記
先頃リリースしましたバージョン0.10で，Plack::Testに対応しました．
以下のように利用する事が可能です．
こうしたテストスクリプトを実行すると，以下のようなドキュメントが返ってきます．
よろしくお願いします．
追記2
Test::JsonAPI::AutodocはJSON-RPCに対応しています．
以下のようなコードを書いてやると動きます．
このテストを実行すると以下のようなマークダウンが得られます．
追記3
describe()はsubtest()のように，describe()の中にTest::Moreのメソッドを記述する事が出来ます．
つまり、describeの中にsubtestを書いたりしても大丈夫です．describeの中にdescribeを書くのだけは駄目です．
