簡単な DSL で REST API のドキュメントを書ける。手軽にキレイなドキュメントが作れて便利でした。

こんな ↓ DSL で作ったドキュメントがこちら。 http://docs.test159.apiary.io/

Store 一覧の取得
GET /stores
< 200
{
    "stores": [
        {
            "id": 1234,
            "name": "金のさら"
        },
        {
            "id": 2345,
            "name": "ピザキャップ"
        }
    ]
}

プレビュー見ながら書けるのでわかりやすい。公開したくない場合はプライベートに設定することもできる。コメントや API のテスト機能もあったりして、なかなか使えそう。

たいていの場合、入出力に使うデータ型を定義してドキュメントに記載すると思うんだけど、そういう機能はないので現状では別のドキュメントを用意する必要がある。でも [json schema 使ったデータ型定義も検討されている]((http://support.apiary.io/forums/120125-general/suggestions/3283512-use-json-schema-to-describe-data-types) みたいだし、期待できそう。

ちなみに印刷用スタイルが定義されているのでブラウザで印刷すればそれなりの出力になります。