はじめに
業務でAPI Blueprint と aglio を使ってAPI仕様書を作成したので、
-
API Blueprintで仕様書を記述 -
aglioを使うためのDocker環境の構築 -
aglioを使って、API Blueprintで記述したファイルを読みやすいドキュメントに変換
という一連の手順を備忘録として残しておく。
今回作成した、API Blueprint で記述したファイルと、 aglio を使うDocker 環境のリポジトリは以下。
API Blueprintとaglioとは
API Blueprint
Web APIの仕様を表現するための様々な文法を持つ言語のこと。
記述形式はMarkdown。
ただのテキストファイルなので、Gitなどのバージョン管理ツールとも相性が良い。
公式サイト
aglio
api blueprintで記述した文書を、読みやすいようにHTMLファイル形式に変換してくれるツール。
Node.jsのパッケージなので、 npm を使ってインストールする。
公式サイト
# インストール
$ npm install -g aglio
手順①： API Blueprint で仕様書を記述
まずは API Blueprint で記述するファイルを作成する。
$ mkdir api-blueprint
$ touch api-blueprint/index.md
作成した api-blueprint/index.md にMarkdownで記述していく。
大まかな書き方としては、見出しレベルごとに、
- 第1見出し：リソースグループ
- 第2見出し：エンドポイント
- 第3見出し：HTTPメソッド
- 第4見出し以降：エンドポイントの説明
となっている。
FORMAT: 1A
HOST: http://localhost:8000
# Group ログイン
## ログイン [/login]
### ログイン [POST]
- Request
- Body
```
{
"email": "test@example.com",
"password": "password"
}
```
- Response 200
- Body
```
{
"user": {
"id": ２,
"email": "test@example.com"
}
}
```
※詳しい記述方式については、以下の公式ページを参照。
API Blueprint | API Blueprint
複数ファイルを読み込む
記述量が多くグループ毎に記述ファイルを分けたい場合は、./api-documents/index.md に以下のように複数のファイルを includeすると、複数ファイルを読み込んで1ページのドキュメントに出力することができる。
（ aligio 側で複数ファイルを指定して実行することは出来ない模様。。）
FORMAT: 1A
HOST: http://localhost:8000
<!-- include(login.md) -->
<!-- include(user.md) -->
手順②： aglio を使うための Docker 環境の構築
Dockerfile と docker-compose.yml を作成する。
$ mkdir docker
$ touch docker/Dockerfile
$ touch docker/docker-compose.yml
./docker/Dockerfile に以下の通り書き込む。
※Node.jsのバージョンや、 WORKDIR の場所は任意。
FROM node:14.17
WORKDIR /app
RUN npm install -g aglio --unsafe-perm
docker-compose.yml に以下の通り書き込む。
version: "3"
services:
aglio:
container_name: api-documents
ports:
- "3000:3000"
build:
context: .
dockerfile: Dockerfile
volumes:
- "../api-blueprint:/app"
tty: true
command: aglio -i index.md -s -h 0.0.0.0
# ./api-blueprint/index.mdを実行し、localhost:3000に出力。
※ aglio を実行するコマンドには色んなオプションがある。詳しくは以下の公式ページを参照。
GitHub - danielgtaylor/aglio: An API Blueprint renderer with theme support that outputs static HTML
手順③： aglio を使って、 API Blueprint で記述したファイルを読みやすいドキュメントに変換
docker-compose.ymlの command に、 aglio を使ってライブレビューサーバーを起動する指示を書いたので、Dockerイメージをビルドしてコンテナを起動する。
$ docker-compose up -d --build
これで [http://localhose:3000](http://localhose:3000) へアクセスすると、以下の画像のように aglio によって生成されたHTMLファイルが表示されるようになっており、 [index.md](http://index.md) を編集すると随時ブラウザに反映することが確認できる。
HTMLファイルを生成する
ブラウザでのプレビューではなくHTMLファイルを生成したい場合は、以下のコマンドを実行する。
$ docker-compose exec api-documents aglio -i index.md -o index.html
これで ./api-document/index.html が生成される。
さいごに
API Blueprint は マークダウン形式で記述することができて、 API仕様書として閲覧するための aglio の用意にも手間は掛からず、サクッと導入しやすい方法だった。
ただし、APIから返るレスポンスの内容を postman などHTTPクライアントツールで一つ一つ確認してマークダウンファイルに貼り付けて、、、という作業は非常に手間だったので、 APIのソースコードから読み取って自動で生成してくれるようなものは無いかなぁと思った。（もしあれば是非教えてください！）
あと aglio のgithubを見ると現時点では最終の更新は2018年で止まっているようなので、nodeのバージョンアップなどに伴い不都合が出てこないかは少し懸念点かなと思った。
今回は導入の容易さからこの方法を採用したが、またの機会に開発初期から swagger を導入するということもやってみたい。
参考記事