これはGalapagos Advent Calendar 22日目の記事です。
こんにちは。ガラパゴスのイバンです。
今回開発している案件ではAPI仕様書の作成を担当しております。 弊社でWeb APIまで実装する場合は大体grape-swaggerのgemで自動生成させますが、 今回はお客さん側で実装されますので仕様書のみが作れるツールがないかを調べてみました。
swaggerで作ることも可能ですが、JSONやYAMLを手で書くのはあんまり気が乗らなくて他にないか もうちょっと調べてみました。
理想的には下記の要素が対応しているツールが良い
- インプットはmarkdown形式
- アウトプットはhtml形式
同時にモックサーバの検討もしてました。この案件は前からmockable.ioを利用されてましたが、ユーザ数やエンドポイント数の制限があって、他に良いサービスかツールがないかを調べてましたところで、api-mockというnode.jsサーバを見つけました。 残念ながらもうメンテされてない状態ですが、気になったのはAPI仕様書からモックサーバを作るツールであって、その仕様書はAPI Blueprintで書けばapi-mockがそれ読み込んでサーバを立ててくれます。
つまり、API Blueprintで仕様書を書けば、モックまでできてしまう。一石二鳥ですね。
早速API Blueprintのサイトを確認すると嬉しい驚きがありました。
API Blueprint
API BlueprintはAPIの記述ができるMarkdownベースの言語です。
# GET /message + Response 200 (text/plain) Hello World!
上記のサンプルは/messageをGETで取得すると"Hello World!"がテキストとして返すという仕様になります。
api-mockにblueprintを渡せば、モックサーバが立ち上がって、ブラウザでモックサーバのアドレスを開くとHello World!というテキストが表示されます。
もちろんjsonを返すことを示すのも可能です。
+ Response 200 (application/json)
[
{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"url": "/questions/1",
"choices": [
{
"choice": "Swift",
"url": "/questions/1/choices/1",
"votes": 2048
}, {
"choice": "Python",
"url": "/questions/1/choices/2",
"votes": 1024
}, {
"choice": "Objective-C",
"url": "/questions/1/choices/3",
"votes": 512
}, {
"choice": "Ruby",
"url": "/questions/1/choices/4",
"votes": 256
}
]
}
]
上記の例ではjson自体を書きましたが、もう一つの書き方はデータ記述です。その場合はMSONを使ってこうなります。
### List All Questions [GET] + Response 200 (application/json) + Attributes (array[Question]) ## Data Structures ### Question + question: Favourite programming language? (required) + published_at: `2014-11-11T08:40:51.620Z` (required) + url: /questions/1 (required) + choices (array[Choice], required) ### Choice + choice: Javascript (required) + url: /questions/1/choices/1 (required) + votes: 2048 (number, required)
jsonはどこへ行った？こっちの方がわかりにくいのでは？ってなるかもしれませんが、説明してないことがあります。A PI Blueprintにはモックサーバ以外、色々なツールがあります。幸いにHTMLレンダラーもありまして、ようやく欲しかったもの全部揃えました。使っているのはAglioというNode.jsライブラリ兼コマンドライン・インターフェースです。
AglioにBlueprintファイルを渡すとhtmlを作成してくれます。しかも、サンプルデータがちゃんとJSONになっていて、しかもJSONスキームも出してくれます。
HTML出力のサンプルはここから見れます。
"Show"のリンクを押すと、リクエストとリスポンスのヘッダー、ボディー、スキームが見れます。
素晴らしいですね。
感想
API BlueprintはMarkdownで書かれますのでgithubなどのバージョン管理システムにアップしてチームで編集できてとても良いです。
関連ツールは充実してて簡単にスタブやhtml作成ができちゃいます。
マイナスなポイントは多分、MarkdownなのでBlueprintの規約的にはどこはキーワードか、どこは自分で自由に書けるか、わかりにくいところがあります。
簡単な紹介になりますが、参考になりましたでしょうか。今後も機会あればAPI Blueprintで仕様書を作成したいと思います。
