概要
この記事ではAPI Blueprint形式でWeb APIの仕様をMarkdownっぽく記述しつつ、aglioで自動的にドキュメント化してみます。
インストール
まずHomebrewでnode.jsをインストールして、npmからaglioのパッケージをインストールします。
# node.jsおよびnpm導入の参考例
$ brew install node
$ npm install -g aglio
(前準備)ダミーのWeb APIを用意する
前準備として、まずはドキュメントを書く対象となる適当なWeb APIを用意します。ここではサンプルとして、以下のサイトに掲載されているPythonのBottleというパッケージで書かれたダミーのRESTful APIを返すサーバを使ってみましょう。
このサイトのbottle/test2.pyは、最低限のCRUD操作が備わったWeb APIを提供するコードです。それぞれレシピのXMLのパスが返ってきたり、レシピを投稿したり削除する機能を模していますが、実際のコードでは単にテンプレのjsonを返すだけのものです。
- http://localhost:8080/recipes：GET
- http://localhost:8080/recipes/name：GET
- http://localhost:8080/recipes/name：PUT
- http://localhost:8080/recipes/name：DELETE
API Blueprint形式のMarkdownを記述する
さて、実際にAPI Blueprintを使ってWeb APIの構造を記述していきましょう。まずはhttp://localhost:8080/recipesにGETでアクセスすると、すべてのレシピのXMLが返ってくるWeb APIの仕様を書いてみます。
なお、詳細なAPI Blueprintの記法等は公式ドキュメントやチュートリアルを参考にして下さい。
FORMAT: 1A
# レシピサイトWebAPIドキュメント
## すべてのレシピのXMLを表示する [/recipes]
### recipes_list [GET]
すべてのレシピのリストを返します。
+ Response 200 (application/json)
+ Attributes
+ success: False (boolean) - ステータス
+ path (array) - XMLファイルパス
+ error: show not implemented yet (string) - エラーメッセージ
まず1行目ではWeb APIのメタ情報としてバージョン情報を記述しています。
2行目以降では、Markdownと同様に見出しと、それに対応するURLやHTTPメソッドの種類を記述しています。これは後のaglioでドキュメント化するときのためのものです。
そして+ Response 200 (application/json)行以降では、具体的にどのようなWeb APIなのかを記述しています。これはMarkdownを拡張したMSONという記法を使って書かれています。ここにレスポンスで返ってくるjsonをそのまま貼り付けることも可能ですが、可読性や変更のしやすさを考えるとMSON記法の方が良さそうです。
さて、このような形式でその他3つのWeb APIについても記述をしていきます。完成版はGistに上げておきました（recipe.apib）。
aglioでドキュメントをHTML形式で出力する
API Blueprint形式でWeb APIの構造が記述できたところで、これを aglioを使って見やすいドキュメントに整形します。
$ aglio -i recipe.apib -o recipe.html
aglioで作成したrecipe.htmlを開くと、以下ようなHTML形式のドキュメントが表示されます。それぞれのWeb APIのレスポンスに加え、JSON Schemaも表示されます。
なお、aglioでは幾つかのHTMLのテンプレートが用意されており、two columnとthree columnといった表示形式を選択したり、テーマ自体を変更することができます。
$ aglio -i recipe.apib -o recipe.html --theme-variables slate --theme-template triple
まとめ
このように、API Blueprint形式のドキュメントを書くだけで、aglioで綺麗なHTML形式のドキュメントを生成することができました。Web APIのドキュメントをテキスト形式で管理できるのでgitなどのバージョン管理との親和性も高いですし、Web APIのスキーマを設計しながらドキュメントも同時に書き進められるのではないかと思います。
一方でデメリットは各所で言われているように、API BlueprintやMSONの形式には癖があって、記法に慣れるのに少し時間は掛かるかもしれません。その辺りは少し我慢をしてサンプルを見つつ頑張って書くほかに、ApiaryというGithubと連携したドキュメント生成のウェブサービスにApiary Editorというエディタが付属しているので、そちらを利用する手もあります。