ローカルで動かそうがDockerで動かそうが、APIを持つアプリを作るとなると自然と一覧が欲しくなるもの。
できれば型や仕様書のフォーマットを... ブラウザで見れる&修正後はDiffが取れる形で欲しいですね。
(自分の関わってたプロジェクトだとExcelにペタペタ定義を書くor貼る仕様書でした。古いとこだと一太郎で作ってた。一太郎2018ってあるんだぜ)
[一太郎] ... フォントや段組機能は好きです www.justsystems.com
そこでAPI仕様書を簡単に作ろうと思った時に当たった選択肢が、Swagger or API Blueprintでした。 今回はAPI Blueprint触った感じを書きます。
[API Blueprint] API Blueprint | API Blueprint
[Swagger] ... こっちの方が The World's Most Popular らしい swagger.io
完成図
一聞は一見にしかず。下図みたいに エンドポイントごとに作成できます。 GETは青色、POSTは緑色とHTTPメソッドごとに色別になっているのはSwaggerと同じ。また、APIもグルーピングができるようです。
基本
マークダウンで書きます。SwaggerはJSON or YAMLで書くので、API Blueprintはマークダウンに慣れている人にはぴったりです。
ただ、マークダウンといっても作成するファイル形式は .apib だったり、段落にも意味があったり、特定のブロックは3tab or 12こスペース空けるといったコード規約があります。ここはクセがありますが、1時間もあれば慣れます。
流れとしては、だいたい4つに分けられます。
- マークダウンで 仕様書を書く
- できたファイルは
.apibで保存 .apibファイルを 変換用のツールでHTMLにする- HTMLをお好きなブラウザで見る
HTML変換ツールも言語・フレームワークによって色々用意されているようですね。 例えば、Aglio: Node.js / Laravel Blueprint Docs: PHP(Laravel) / django-apiblueprint-view: Python(Django) / Snowboard: Go といった具合です。 API Blueprint Tools | API Blueprint
また、書いたマークダウンを元にAPIのモックサーバーを動かせるんですが、MacOS10.12以降では動かないみたいですね。。。
→ issuesに上がってました。
書けること
だいたい以下のようなことをかけます。
HTML生成時にリクエストパラメータやレスポンスデータのスキーマを必須・オプション、データ型含めてまとめて表示してくれるのは嬉しい。
面倒なポイント
私は幸いにもマークダウンは普段から書いてる & Node.jsの例は豊富にあったので書くこと自体は苦はないですが、 aglioでの面倒な点として.apib 1ファイルしか変換できないこと がネックでした。１ファイルじゃなくて、分割して書いたものを1つにまとめたいじゃないですか。
少し前の記事ですが、他の方も複数ファイルあるものを1つの.apibファイルにまとめて変換をかけているような手段をとっているようです。
というわけで、シェルスクリプト書いて分割した.mdファイルを1つの.apibファイルにまとめて変換しました。
→ Gistで公開してます。(マークダウンはソース貼り付けるとGist上で読みやすく変換してくれるおかげでソースコード見れなくなってますが笑)
作成した仕様書はGithubPagesやローカル、社内のサーバーに置くなりすれば立派な仕様書ができそう。
