blueprint で API仕様書

概要

Markdown形式で記述するAPI BlueprintでのAPI仕様書作成とHTMLへの出力方法です。

1. レンダラ(aglio)のインストール
2. Api Documentの記述
3. HTML出力
4. テスト

1. aglioのインストール

nodeのバージョンが v8.x でないと動かないので、バージョンを変更しておく。

$ mkdir blueprinttest
$ cd blueprinttest
$ nodenv install 8.17.0
$ nodenv local 8.17.0

aglioをインストール

$ npm install aglio

2. Api Documentを書く

ドキュメントファイルを作成してコードエディタとかで開く。

$ touch test.apib
$ code .

次のようにAPI Blueprintの仕様に従いapi仕様書をかく。

書き方はこちらを参考に。

• API Blueprint tutorial
  • https://apiblueprint.org/documentation/tutorial.html

FORMAT: 1A
HOST: http://localohst/

# API ドキュメント大見出し

## このドキュメントのみかた

このドキュメントに定義されているAPIは以下のグループで構成されています。

- A Group
- B Group

## Headerについて

このAPIは認証トークンが必要です。各APIには次のようにヘッダにトークンを設定します。

```
Authorization: Bearer {token}
Content-Type: (application/json)
```

## Responseについて
Response Body は JSON オブジェクトとして次の形式で戻ります。

```
{ 
    "status" : "Success",
    "field1" : "データ1",
    "field2" : "3211",
}
```

# Group A
A GroupのAPIを定義します

## 名前取得A [/api/beta/v1/name/get]

指定したIDで名前を取得するAPIです。

### 名前取得A [POST]

+ Request
    + Headers

        ```
        Authorization: Bearer {token}
        Content-Type: (application/json)
        ```

    + Attributes
        + id: 1 (string, required) - ID

+ Response 200 (application/json) 
    + Attributes
        + status (string ,required) - 成功時はSuccess、失敗時はFail
        + name: "名前" (string, required) - 名前


# Group B
B GroupのAPIを定義します

## 名前取得B [/api/beta/v1/nameb/get]

指定したIDで名前を取得するAPIです。

### 名前取得B [POST]

+ Request
    + Headers

        ```
        Authorization: Bearer {token}
        Content-Type: (application/json)
        ```

    + Attributes
        + id: 1 (string, required) - ID

+ Response 200 (application/json) 
    + Attributes
        + status (string ,required) - 成功時はSuccess、失敗時はFail
        + name: "名前" (string, required) - 名前

3. HTML出力

aglioコマンドでHTML出力します。

aglio -i test.apib -o test.hml

-i で元ファイル、-o でHTMLとして出力するファイル名　を指定します。
実行後指定したHTMLファイルが生成されています。
開くとこんな感じ。

4. テスト

既にAPIが開発環境にあり、ドキュメントがテスト通りかテストしたい場合は dredd というプラグインを使います。

npm install -g dredd

これで次のようにテストしたい仕様書とAPIサーバURLを指定すればOKです。

dredd test.apib http://localhost