API Blueprintを試す

仕事でアプリをSPAで開発することになり、バックエンドとREST APIでやり取りする必要がでてきたので、 APIのHTMLドキュメント＆モックサーバを実現するツールを探していたところ、API Blueprintに辿り着きました。

似たようなツールとしてSwaggerもありますが、覚えることが多く、学習コストが高そうな印象でした。 ただ、サードパーティー製のツールは豊富にあるので、長く使うのであればSwaggerの方が良いのかな？という印象です。 （実際にまだ試していないのでなんとも言えないですね・・）

今回は、サクッとAPIのドキュトメント＆モックサーバを用意したかったのでAPI Blueprintにしました。

API Blueprintとは

公式サイト

Markdownで書けるAPI仕様書になります。 書いたAPI仕様書は、HTMLに変換したり、モックサーバにしたり、テストできたりまします。 Markdownなので、gitで管理して差分管理もしやすいメリットがあります。

実際に使ってみる

APIのHTMLドキュメント＆モックサーバを試してみます。

API Blueprintの書き方はこちらのスライドを参考にさせて頂きました。
Apiドキュメンテーションツールを使いこなす【api blueprint編】

API仕様書を、HTMLドキュメント＆モックサーバとして動かすには、以下のnpmパッケージをインストールします。

• aglio（HTMLドキュメント）
• drakov（モックサーバ）

$ npm install -g aglio
$ npm install -g drakov

aglio

API仕様書をHTMLドキュメントで閲覧するにはaglioを使用します。

まず、index.mdを用意します。
foo.md、bar.mdはそれぞれAPI仕様書です。

FORMAT: 1A

<!-- include(api/v1/foo.md) -->
<!-- include(api/v1/bar.md) -->

以下のコマンドでaglioを起動します。

$ aglio -i index.md -s -h 0.0.0.0 -p 3001

http://localhost:3001 にアクセスするとHTMLドキュメントが閲覧できます。

aglioの主な機能はこちらになります。

• ライブリロード（編集しながら内容を確認できます）
• 文法エラーチェック（コンソールに構文エラーが出力されます）
• ファイル分割（APIの纏まりでファイルを整理できます）

drakov

drakovでモックサーバを起動してみます。

以下のコマンドでdrakovを起動します。

$ drakov -f **/*.md --public --watch --p 3002

http://localhost:3002 にアクセスするとAPI仕様書に従ったレスポンスが返却されます。 --watchオプションを付けると、ライブリロード機能が有効になり、API仕様書を編集すると即反映されます。

レスポンスは、ResponseのAttributes or Bodyに書いた内容が返却されます。

+ Response 200 (application/json)
  + Body
    ```
    { message: "Hello world" }
    ```

Bodyにレスポンスを貼り付けるとそのままレスポンスとして返却されます。 サクッと確認したいときはBodyに書いて、きちんと設計したいときはAttributesに書いていくのが良い気がします。 最終的にはAttributesに書く感じになるかと思います。

まとめ

SPAのアプリとバックエンドを並行して開発する場合、API Blueprintは非常に便利なツールに感じました。 モックサーバを簡単に作成できるので、バックエンドがボトルネックになる心配もありません。 また、API仕様書として残るので、アプリ⇔バックエンド間のI/Fのすりあわせがしやすくなります。

今回は、API仕様書のテスト(Dredd)は試せてないので、次回試してみたいと思います。 また、API BlueprintのAPI仕様書をクラウドで管理できるApiaryもあるんですね。