API BlueprintでAPI仕様を書く

2016-11-10 document

API BlueprintというのはAPIの仕様を書くための言語で、これを元にHTMLのドキュメントにしたり、モックサーバーを立てたりするツールがある。

最初にMetadataとして、API Blueprintのバージョンを書く。

FORMAT: 1A

基本的にはMarkdownのように書ける。

# テストAPI
テスト

頭にGroupと書くとグループができる。

# Group echo
やまびこ

終わりに[]で囲んでリソースを書く。

## echo [/echo]
やっほー

アクション。

### echo [POST]
叫ぶ

+ say (string) - 発声

リクエスト例とレスポンス例はこんな感じ。JSON Schemaを書くこともできる。

+ Request (application/json)

    {
        "say": "yahho"
    }

+ Response 200 (application/json)

  + Headers

    Hoge: Fuga

  + Body

    {
        "echo": "yahho"
    }

全体

FORMAT: 1A

# テストAPI
テスト

# Group echo
やまびこ

## echo [/echo]
やっほー

### echo [POST]
叫ぶ

+ say (string) - 発声

+ Request (application/json)

    {
        "say": "yahho"
    }

+ Response 200 (application/json)

  + Headers

    Hoge: Fuga

  + Body

    {
        "echo": "yahho"
    }

これを使って、aglioでHTMLにしたり、

$ npm install -g aglio
$ aglio -i test.apib -o test.html

api-mockでモックを立てたりすることができる。

$ npm install -g api-mock
$ api-mock --version
api-mock v0.3.2

$ api-mock test.apib
info:    Enabled Cross-Origin-Resource-Sharing (CORS)
info:    	Allow-Origin: *
info:    	Allow-Methods: GET, PUT, POST, PATCH, DELETE, TRACE, OPTIONS
info:    	Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization, Referer, Prefer
info:    Listening on port 3000

ただnode v6でインストールしたらprotagonistのところで失敗してしまったので、5.12.0に下げて実行した。

nでNode.jsのバージョン管理

$ n 5.12.0

$ curl -X POST -H "Content-Type: application/json" -d '{"say": "ho"}' "http://localhost:3000/echo"
{
    "echo": "yahho"
}