Docker環境でAPI Blueprint+aglioを使ってAPI仕様書を作成する #Docker

はじめに

業務でAPI Blueprint と aglio を使ってAPI仕様書を作成したので、

API Blueprint で仕様書を記述
aglio を使うための Docker 環境の構築
aglio を使って、 API Blueprint で記述したファイルを読みやすいドキュメントに変換

という一連の手順を備忘録として残しておく。

今回作成した、API Blueprint で記述したファイルと、 aglio を使うDocker 環境のリポジトリは以下。

API Blueprintとaglioとは

API Blueprint

Web APIの仕様を表現するための様々な文法を持つ言語のこと。

記述形式はMarkdown。

ただのテキストファイルなので、Gitなどのバージョン管理ツールとも相性が良い。

公式サイト

API Blueprint | API Blueprint

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 を導入するということもやってみたい。

Docker環境でAPI Blueprint+aglioを使ってAPI仕様書を作成する