WebAPIドキュメント作成サービス apiary.ioを使ってみた

apiary.ioを使ってみました。
WebAPI(REST API)のドキュメントをサクっと書けるサービスです。
http://apiary.io/

去年(2012)年にローンチされたサービスで、何かに使いたいな〜と思いつつ...。
今回、開発中のWebサービスにWebAPIを実装することとなったので使わせていただいております。 (そのドキュメントはまだ公開してないです。すみません(汗;))

以下のように、API Blueprintという簡単な文法で、
"リクエスト"と"レスポンス"の例を記述するだけで
便利なドキュメントができあがります。

HOST: http://api.example.com/
--- ほげほげ API v2 ---
---
Welcome to our API. Comments support [Markdown](http://daringfireball.net/projects/markdown/syntax) syntax.
---
-- Shopping Cart Resources --
GET /shopping-cart
> Accept: application/json
< 200
< Content-Type: application/json
{ "items": [
    { "url": "/shopping-cart/1", "product":"2ZY48XPZ", "quantity": 1, "name": "New socks", "price": 1.25 }
  ] }

(ちなみに、descriptionなどの項目は、Markdownベースの記法を利用できるようになっています。)

作成されたドキュメントページ： http://docs.test0mugifly.apiary.io/
(ドキュメント上に記載されたWebAPIは実在しません。あしからず。)

簡単に使い方を説明しておきますと・・・。
まず...何が便利なのかというと・・・

この記述をもとにして、
テストリクエストを受けるための"Mock Server"を自動で用意してくれます。

このように Mock Serverが自動的に使えるようになる。

このMock Serverはドキュメントに記述したままのレスポンスを返すことができる他、
Proxyとして動作させることもでき、テスト用アクセスを識別するためのHTTPヘッダを自動付加して、productionなWebAPIサーバへアクセスさせる事も可能です。
(つまり、ドキュメント(仕様書)のリクエスト/レスポンスと、実際のクライアントによるリクエスト / 実際のWebAPIによるレスポンスを比較することができるわけです。)

"Inspector"タブでは、全てのリクエストの履歴一覧と詳細確認が行える。
リクエストヘッダ、レスポンスヘッダ、レスポンスボディについて各々、
ドキュメント(仕様書)に記述されたものと、実際の結果との比較が可能。

apiary.ioのドキュメント設定画面。
Cross-Origin Requestのヘッダを付加したり、Mock ServerをProxyにすることが可能。

また、JavaScriptやpythonによるアクセスのためのサンプルコード表示ができたり...

ドキュメントページの"Example"タブでは、
各プログラミング言語によるサンプルコードの表示を行える。
(個人的には...perlによるサンプルコードは用意されていないのが少々不満(笑))

ブラウザ上でXMLHTTPRequestによるテストリクエストを行えたり...

おなじく、ドキュメントページの"Try it"タブでは、
XMLHTTPRequestによるテストリクエストをその場で行える。

また、コメントによるディスカッションもでき...結構至れり尽くせりな気がします。

おなじく、ドキュメントページの"Comment"タブでは、
各resourceごとにスレッドを立ててコメントが書ける。

この手軽さでありながら、大手サービスのWebAPIドキュメントにも引けをとらないレベルといっても良いかもしれませんね。

作成したドキュメントは、一部登録メンバーのみ閲覧可能なように、Privateにすることもできます。
また、GitHubのリポジトリでドキュメントを管理することもでき、プッシュするだけで更新が可能になっています。複数人編集も楽ですね。
(apiary.io上のエディタで編集したほうが、完全なライブプレビューが出来るので便利かもしれませんが。)

"WebAPIドキュメントを書こうと思っても...ふつうのWikiページなどに書くのは面倒くさいな〜"という場合も、使ってみるとかなり便利だと思います。
今のところベータバージョンですが、これで無料ですし、試してみてはいかがでしょうか。