こんにちは、エンジニアのナカハシです。
隠れドラゴンズファンなので久々に観戦に行ったら、10点差を追いつかれてサヨナラ負けしました。世知辛いにもほどがありますね！！！！！！！(怒)(泣)
サーバーサイドとフロント/アプリを別チームで開発するといったケースでは、互いのシステムのインターフェイスはAPIになります。なので、API定義の共有は重要です。
APIのドキュメンテーションやチーム開発を支援する、API BluePrintについて、色々試してみました。
なにそれ？
API BluePrint は、API用に特化したドキュメンテーションのための言語です。以下のような特徴があります。
- 主にMarkdownで書く → 誰でも読み書きできる
- きれいなドキュメント出力
- モックサーバーも作れる
とにかく書く
まずはAPIの概要を書きます。公式のExample が充実しているので見ながら書くといいでしょう。雰囲気はこのような感じです。
FORMAT: 1A
HOST: https//api.example.com
# /message
リソース名書く。
## GET
GETの場合の機能を書く。
+ Response 200 (text/plain)
+ Headers
X-My-Message-Header: 42
+ Body
{ "message": "Hello World!" }
最初の FORMAT: 1A は、API BluePrintのバージョンです。
+ Response 200 (text/plain) 以降はこのAPIの内容を記述している部分です。ここだけは記法が独自になりますが、シンプルな仕様なのですぐに覚えられるでしょう。
細かい話ですが、インデントで使うスペース数は固定で4つです。そして + Headers や + Body の次のインデントは一見2段目に見えるのですが、3段目（12スペース）にする必要があります（さもないと、後述の出力ツールで警告出ます）。この辺は若干罠ですが、とにかく公式通りに書きましょう。
HTMLに出力してみる
API BluePrint自体はただの記述言語なので、出力するためのツールが必要です。今回は割とよく使われている Aglio を試してみましょう。npmモジュールです。
先ほど「とにかく書いた」APIを出力してみましょう。
$ vim index.md # とにかく書く $ npm install aglio $ node_modules/.bin/aglio --theme-variables slate -i index.md -o ./index.html
これだけで、カレントディレクトリに美しいドキュメントが出力されてます！
GitHub Pagesに出力してみる
GitHubには、簡単に静的ページを公開できる GitHub Pages という機能があります。せっかくHTMLに出力したので、Github Pagesを公開してみましょう。
GitHub PagesでHTMLを公開するのは簡単で、gh-pagesというブランチを切り、そこにindex.htmlを格納すればいいだけです。
API BluePrintで書いたMarkdownファイルですが、もちろんGitなどの構成管理ツールで管理すべきです。そしてこれをソースとしてAglioでHTMLを出力して閲覧するという使い方を考えると、HTMLはコンパイル結果のバイナリみたいなもので、構成管理ツールでの管理対象ではなくてもいいはず。
以上により、API BluePrintファイルをapi-docブランチで管理し、そこで得られるHTMLをgh-pagesにpushするという方法を考えました。API BluePrint→HTMLへの変換とgh-pagesへのpushは、CircleCIで自動化します。api-docブランチへのpushをトリガに動かせるといい感じです。
上記のような circle.yml のサンプル を書いてみました。
出力結果は こちら で見れます。
いい感じにできたとは思うのですが、GitHub Pagesは（privateリポジトリであっても）無制限に公開されちゃいます。用途的にOKならこの手を試してみましょう。
ドキュメントを動かす
非常に良いのが、ドキュメントがそのままモックサーバーになってくれることです。
さきほどとにかく書いた手順に続けて、モックサーバーを動かしてみましょう。モックサーバーはいくつか選べますが、手元で動かせたのは drakov でした。
$ vim index.md # とにかく書く $ npm install drakov $ node_modules/.bin/drakov -f index.md -p 8081 --watch [INFO] No configuration files found [INFO] Loading configuration from CLI DRAKOV STARTED [LOG] Setup Route: GET /message Drakov 1.0.4 Listening on port 8081 FILE SPY ACTIVE
何やらうごめいています。curlで突っついてみましょう。
$ curl http://localhost:8081/message { "message": "Hello World!" }
ドキュメントに書いた内容が返ってきました。スゴい！
競合とワークフロー
API Blueprint創始者が語るAPIの進歩 という記事がおもしろかったので、少し引用します。
Swagger v2.0やRAML v0.8と比較した時，API Blueprintの最大の強みは何でしょう？
Jakub Nestril: API Blueprintは最もヒューマンフレンドリなフォーマットです。開発者やプロダクトマネージャ，ドキュメントライタ，アーキテクトといった人たちに広く利用されています。最大の強みは，このすべてを同じテーブルで提供できることです。
YAMLなどのフォーマットで書くと、パースエラーなど色々面倒なことがありますからね。
API Blueprintを使用する場合，基本的な開発ワークフローはどのようなものになりますか？
JN: ワークフローでもっとも画期的なのは，APIバックエンドチームとAPI利用チームが，APIの両側で並行して共同設計，共同開発ができることです。Apiaryでまず最初に，モックサーバを構築した理由がここにあります。
「共同設計」「共同開発」のために、書きやすいMarkdownライクなフォーマットとすぐ動くモックサーバーを採用しているということがわかります。
アジャイルスタイルのいまどきの開発に、とてもマッチしているのではないでしょうか？
まとめ
10点差あっても、勝ちパターンの投手を出していく慎重な姿勢が大事です。