Galapagos Blog

株式会社ガラパゴスのメンバーによるブログです。

API Blueprintで仕様書を作ってみた

これはGalapagos Advent Calendar 22日目の記事です。

こんにちは。ガラパゴスのイバンです。

今回開発している案件ではAPI仕様書の作成を担当しております。 弊社でWeb APIまで実装する場合は大体grape-swaggerのgemで自動生成させますが、 今回はお客さん側で実装されますので仕様書のみが作れるツールがないかを調べてみました。

swaggerで作ることも可能ですが、JSONYAMLを手で書くのはあんまり気が乗らなくて他にないか もうちょっと調べてみました。

理想的には下記の要素が対応しているツールが良い

  • インプットは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で仕様書を作成したいと思います。

参照

API仕様書フレームワーク

API Blueprintツール

その他