REST APIドキュメント作成ツールはapiary.ioが決定版かもしれない

2883 ワード
Markdown api document Markdown テキストリンク

背景

これまでずっとREST APIドキュメントをwiki上で管理していて、重たいページ上で特殊記法使ったり、スタイルの調整に時間を取られるのが辛かった。そこで良さげなドキュメントツールを色々調べてたんだけど、最終的にapiary.ioが一番良さそうという結論になってきた。

このサービスの主な特徴。

  • markdown記法でAPIドキュメントを記述できる
  • ドキュメントの生成と同時にAPIのモックサーバを用意してくれる
  • サインアップから5分くらいあればドキュメント公開できる。ドキュメントのホスト先を気にしなくてもいい。

特にドキュメントと一緒にモックを作ってくれるのは他にはないポイントでかなり便利。

使ってみる

サインアップはGithubアカウントで http://apiary.io から。ログインしたら↓のようなサンプルのAPIドキュメントが用意されていて、ページ上のエディタですぐに弄って見た目をプレビューできる。

ドキュメントの記述はMarkdownライクな記法が使える。試しに1個APIを追加してみる。

# ユーザ情報API
## ユーザ情報へのアクセス [/user/{id}]

### ユーザ情報を取得する [GET]
+ Response 200 (application/json)

        {
          "nickname": "horimislime",
          "livetown": "tokyo"
        }

H1で一つのAPIグループを定義して、H2でそのAPIに属するエンドポイントを記述する。更にH3でエンドポイントがサポートしているHTTPメソッド毎のレスポンス例が書ける。上の例だと/user/{id}へのGETリクエストがstatus 200の場合に返ってくるjsonのbodyを記述している。

これだけ書いて保存すれば、即座にAPIドキュメントがグローバル公開される。
horimislimeのてすと API—by apiary.io

更に便利なことに、 ここで書いたリクエストやレスポンス形式を元にAPIのモックサーバまで生成してくれる！上の例だと http://horimislime.apiary-mock.com/user/{任意のID} にリクエストを飛ばせば定義しておいたサンプルレスポンスが返ってくる。

わざわざcurlとか叩かなくても、ドキュメントページ上のTry Itからリクエストを投げてレスポンスを確認することもできる。便利！

おわり

使ってみた印象、サインアップしてすぐ使えるのが楽で、しかもmarkdownベースな記法ですんなり書けるのがとにかく大きいと思った。チーム開発現場で新しいツール入れる時、導入とか学習のコストが悩みの種だけどこれなら入れる敷居も高くない気がする。

モックの自動生成も魅力的で、サーバサイドのAPI実装がなかなか進まない時クライアント側がAPI待ち状態になって申し訳ない感じになるけど、apiaryで書いておけば仕様決めてドキュメント渡すと同時にモックでテスト進めてもらえるから効率良さそう。