API BlueprintでAPI仕様書を書いてみる 導入編

チームでAPI仕様書の書き方を統一しようということになって、API Blueprintを使ったらとても便利でした。

良い点

• マークダウンが使える
• わかりやすい
• 見た目がかっこいい！

やること

API Blueprintは拡張子が.apibなのでhtmlに変換するためにaglioをインストールします。
インストールするにはnpmが必要なのでnpmをインストールします。

Node.js/npmをインストールする

• mac版
  https://qiita.com/mk185/items/7ad004bf202f400daea1
  （LTS：長期の保守運用向けバージョン/CURRENT:最新版だけど安定性は保証していないことで機能追加を盛り込んだバージョン）

• windows版
  https://qiita.com/taiponrock/items/9001ae194571feb63a5e

aglioをインストールする

$npm install -g aglio

apibファイルを作成

https://apiblueprint.org/documentation/examples/real-world-api.html
Real World APIをエディタにコピペして拡張子.abibで保存

ローカルで確認

$aglio -i <コピペした保存したファイル名.apib> --s

ブラウザで以下アクセスする保存したサンプルAPIファイルが表示される
http://localhost:3000/

HTMLファイルに生成する場合

aglio -i <コピペした保存したファイル名.apib> -o <HTMLに変換したいファイル名>.html

できあがり

新規でapibファイルを作成

apibファイルの中身はこれー↓↓

# Group サンプルページ


## 会社情報 [/api/company/{cityId}/]

### 会社情報取得API [GET]

#### 処理概要

* サンプル会社情報取得

+ Parameters

    + cityId: 27210 (number, required) - 市区町村ID

+ Response 200 (application/json)

    + Attributes
        + data (required)
            + areaData (required)
                + cityId: 27210 (number)  - 市区町村ID
                + cityName: 枚方市 (string)  - 市区町村名
            + clientData (required)
                + image: /images/sample.jpg (string, required)  - ロゴ画像
                + name: サンプル株式会社 (string, required)  - 会社名
            + image
                + exterior  (array[object], fixed-type)
                    + (object)
                        + image:  /images/sample1.jpg (string)  - 画像ファイルパス
                        + caption: サンプル画像  (string)  - 画像説明文

git管理してメンバーで共有しております。

書き方について詳しくは次回！！！

VS CODEを使ってる人は「API Elements extension」の拡張機能を使うと便利です。