読者です 読者をやめる 読者になる 読者になる

HDE BLOG

コードもサーバも、雲の上

APIの仕様をMarkdownで定義する

おはこんばんちは!! 尾藤 a.k.a. BTO です。

Web APIの仕様の定義ってみなさんどうされているでしょうか。 人によって書き方がバラバラだったり、定義に過不足があったりしてないでしょうか。 Web APIのインターフェースで定義する内容は、ほとんど決まってます。 もっと形式的な書き方できないだろうかと探してみたら、やはり同じ事を考えている人がいて、API Blueprintというのを見つけました。

API Blueprint - API Documentation with powerful tooling

API Blueprintを使うとMarkdownAPIの定義ができます。

できること

APIの記述フォーマットが決まっていますので、どこで何が定義されているかが分かります。 ですので、機械的に処理する事ができるようになります。 具体的には、

  • APIドキュメントの生成
  • 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

Snow Crash

API Blueprintの処理の中心となる C++ で書かれた、ツール&ライブラリです。 Snow Crash を直接使う事はあまりなく、大抵の場合使用するツール経由で使用する事になりますので、あまり存在を意識する必要はありません。

Aglio

Aglio

nodejs のツールで、API Blueprintで定義されたドキュメントをHTMLで表示してくれます。 こんな感じにかっこよく表示してくれます。

f:id:masatobito:20150116124624p:plain

api-mock

api-mock

その名の通り、API Blueprintで定義されたAPIのモックサーバをいきなり立ち上げてくれます。 プログラムを1行も書かなくても、いきなりAPIの動作確認ができます。

他のツール

API Blueprintのページには、他のツールも紹介されています。 ツールだけじゃなくて、クラウドサービスなんかもあるようです。

まとめ

Web API定義は API Blueprint で定義すれば、機械的に処理できるようになり、誰が書いても共通の書き方に統一できる。