API仕様書 API blueprint でつくってみる
microCMS を使っているプロジェクトがあり、はじめてAPIというものをそれらしく作っているのですがドキュメント出力みたいな機能はなさげなのでサードパーティーのツールを調べて使ってみました。
まず有名どころとしては
があるらしいですね。Swaggerは他の案件でも使われているのは見ていて、API GatewayへもSwaggerで作ったファイルをインポートできるとかをデベロッパー資格の勉強の際に見たので知ってました。
ただSwaggerは高機能が故、複雑そうで学習コストも高いとのこと。
なので最初は API blueprint を使ってみることにしました。
API blueprint とは
APIの仕様書を簡単にかつ明確にドキュメントにできるツール(言語)
API Blueprint でAPI設計書を書く 超入門編 Part1 - Qiita
言語というのを知らなく単純なツールと勘違いしていたのですが、 sample.apib みたいな API blueprint 用のファイル（マークダウン形式のドキュメント）を用意して、それをhtmlに変換して共有なりをする流れで使うようです。
仕様書の作成
早速やってみました。
.apib ファイルの作成
今回は /docs/sample.apib というファイルで下記を書いてみます。
FORMAT: 1A
HOST: http://localhost/api
# Sample API
this is sample API document.
## データの説明 [GET /user]
ここにデータの説明が入ります。
+ Request
+ Headers
```
Authorization: {token}
```
+ Response 200 (application/json)
+ Body
```
{
"id": 1,
"name": "sample-name"
}
```
ドキュメントのプレビュー
aglio というレンダラーを使うと、ローカルサーバーを立ててプレビューしたり、.htmlへの出力ができる。
aglio のインストール
$ npm install -g aglio
node.js のバージョン、12.x系 だとエラーになったので v10.15.0 でインストールしました。
$ cd docs $ aglio -i sample.apib --server
とすると http://127.0.0.1:3000/ でプレビューできるので、 .apib を編集してプレビューしてを繰り返す。
ドキュメントのHTML生成
$ cd docs $ aglio -i sample.apib -o sample.html
で (sample).html が生成される。
aglio -i [input file] -o [output file] の形式です。
--theme-variables slate --theme-template triple のようにオプション付与すると、htmlテーマやレイアウトの変更が可能。
書き方
API Blueprintはとっつきやすい評があったものの、自分はちょいと試行錯誤しながらやりました。
公式 をちょろちょろ見ながらやりましたが、雛形分からないのでQiitaから拾ってきてそれベースに改良。
microCMSの場合下記を使いまわせばBodyとSchemaが構造通りになるかと
FORMAT: 1A
HOST: https://hoge.microcms.io/api/v1
# hoge
hoge
## 一覧 [GET /hoge]
一覧
+ Request
+ Headers
```
X-API-KEY: `APIキー`
```
+ Response 200 (application/json)
+ Attributes
+ contents (array[object], fixed-type)
+ (object)
+ id: `XXXXX` (string) - ID
+ text: `XXXXX` (string) - テキストフィールド
+ img: (object) - 画像
+ url: `XXXXX` (string)
+ multi: (array[object], fixed-type) - 複数コンテンツ参照
+ (object)
+ id: `XXXXX` (string) - コンテンツID
つまづきポイントとして type を array にしたときにうまく Body に反映されないみたいなことが起こったのですが、(array[object], fixed-type) と書けばいけました。（下記参照）
API Blueprint(aglio)で、生成されたSchemaのarrayにitemsがない - Qiita
変数とかいろいろ使えるみたいですが、全体の10%も理解できていなそう..なので引き続き機会あればいじってみようと思います。