Web APIの仕様の定義ってみなさんどうされているでしょうか。 人によって書き方がバラバラだったり、定義に過不足があったりしてないでしょうか。 Web APIのインターフェースで定義する内容は、ほとんど決まってます。 もっと形式的な書き方できないだろうかと探してみたら、やはり同じ事を考えている人がいて、API Blueprintというのを見つけました。
API Blueprint - API Documentation with powerful tooling
API Blueprintを使うとMarkdownでAPIの定義ができます。
できること
APIの記述フォーマットが決まっていますので、どこで何が定義されているかが分かります。 ですので、機械的に処理する事ができるようになります。 具体的には、
などが専用ツールを使ってできるようになります。
記述例
例えば、メッセージを取得・更新するWeb APIを定義します。 API Blueprint(Markdown)での記述例は、下記のようになります。
# メッセージ [/message] メッセージを書き込んだり、読み込んだりするAPIです。 ## メッセージ取得 [GET] メッセージを取得します。メッセージはプレーンテキストで返ってきます。 + Response 200 (text/plain) + Body こんにちは、世界!! ## メッセージ更新 [PUT] メッセージを更新します。 + Request (text/plain) + Body こんばんは、世界!! + Response 204
見て分かる通り、Markdownとしても問題なく読めます。
簡単なフォーマットの説明
上記記述例を元に、軽くフォーマットの説明をします。
# メッセージ [/message]
メッセージを書き込んだり、読み込んだりするAPIです。
リソースの定義をしています。 ここではメッセージリソースを/messageにしています。 以降、これより小さい見出しは、全てメッセージリソースに対するAPIの定義になります。
## メッセージ取得 [GET] メッセージを取得します。メッセージはプレーンテキストで返ってきます。 + Response 200 (text/plain) + Body こんにちは、世界!!
メッセージリソースに対して、GETでアクセスしたときの仕様を定義しています。 Status Code、Content Type、Response Bodyの例を定義しています。
## メッセージ更新 [PUT] メッセージを更新します。 + Request (text/plain) + Body こんばんは、世界!! + Response 204
メッセージリソースに対して、PUTでアクセスしたときの仕様を定義しています。 定義している内容は、GETの時とほぼ同じです。
Snow Crash
API Blueprintの処理の中心となる C++ で書かれた、ツール&ライブラリです。 Snow Crash を直接使う事はあまりなく、大抵の場合使用するツール経由で使用する事になりますので、あまり存在を意識する必要はありません。
Aglio
nodejs のツールで、API Blueprintで定義されたドキュメントをHTMLで表示してくれます。 こんな感じにかっこよく表示してくれます。
api-mock
その名の通り、API Blueprintで定義されたAPIのモックサーバをいきなり立ち上げてくれます。 プログラムを1行も書かなくても、いきなりAPIの動作確認ができます。
他のツール
API Blueprintのページには、他のツールも紹介されています。 ツールだけじゃなくて、クラウドサービスなんかもあるようです。
まとめ
Web API定義は API Blueprint で定義すれば、機械的に処理できるようになり、誰が書いても共通の書き方に統一できる。
