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

## はじめに

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

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

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

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

https://github.com/hinakonagao/API-Blueprint-with-aglio

## API Blueprintとaglioとは

### API Blueprint

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

記述形式はMarkdown。

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

公式サイト

[API Blueprint | API Blueprint](https://apiblueprint.org/)

### aglio

api blueprintで記述した文書を、読みやすいようにHTMLファイル形式に変換してくれるツール。

Node.jsのパッケージなので、 `npm` を使ってインストールする。

公式サイト

https://github.com/danielgtaylor/aglio

```sh
# インストール
$ npm install -g aglio
```

## 手順①： `API Blueprint` で仕様書を記述

まずは `API Blueprint` で記述するファイルを作成する。

```sh
$ mkdir api-blueprint
$ touch api-blueprint/index.md
```

作成した `api-blueprint/index.md` にMarkdownで記述していく。

大まかな書き方としては、見出しレベルごとに、

- 第1見出し：リソースグループ
- 第2見出し：エンドポイント
- 第3見出し：HTTPメソッド
- 第4見出し以降：エンドポイントの説明

となっている。

```md
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](https://apiblueprint.org/)

### 複数ファイルを読み込む

記述量が多くグループ毎に記述ファイルを分けたい場合は、`./api-documents/index.md` に以下のように複数のファイルを `include`すると、複数ファイルを読み込んで1ページのドキュメントに出力することができる。

（ `aligio` 側で複数ファイルを指定して実行することは出来ない模様。。）

```markdown
FORMAT: 1A
HOST: http://localhost:8000

<!-- include(login.md) -->
<!-- include(user.md) -->
```

## 手順②： `aglio` を使うための `Docker` 環境の構築

 `Dockerfile` と `docker-compose.yml` を作成する。

```sh
$ mkdir docker
$ touch docker/Dockerfile
$ touch docker/docker-compose.yml
```

 `./docker/Dockerfile` に以下の通り書き込む。

※Node.jsのバージョンや、 `WORKDIR` の場所は任意。

```sh
FROM node:14.17

WORKDIR /app

RUN npm install -g aglio --unsafe-perm
```

 `docker-compose.yml` に以下の通り書き込む。

```sh
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](https://github.com/danielgtaylor/aglio#:~:text=install%20%2Dg%20aglio-,%E6%AC%A1%E3%81%AB%E3%80%81HTML%E3%81%AE%E7%94%9F%E6%88%90%E3%82%92%E9%96%8B%E5%A7%8B%E3%81%97%E3%81%BE%E3%81%99%E3%80%82,-%EF%BC%83%E3%83%87%E3%83%95%E3%82%A9%E3%83%AB%E3%83%88%E3%81%AE%E3%83%86%E3%83%BC%E3%83%9E)

## 手順③： `aglio` を使って、 `API Blueprint` で記述したファイルを読みやすいドキュメントに変換

 `docker-compose.yml`の `command` に、 `aglio` を使ってライブレビューサーバーを起動する指示を書いたので、Dockerイメージをビルドしてコンテナを起動する。

```sh
$ docker-compose up -d --build 
```

これで `[http://localhose:3000](http://localhose:3000)` へアクセスすると、以下の画像のように `aglio` によって生成されたHTMLファイルが表示されるようになっており、 `[index.md](http://index.md)` を編集すると随時ブラウザに反映することが確認できる。
![スクリーンショット 2022-04-01 15.02.54.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1208065/5acd052e-44ae-2b25-01e9-57e602a3bb3a.png)

## HTMLファイルを生成する

ブラウザでのプレビューではなくHTMLファイルを生成したい場合は、以下のコマンドを実行する。

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

## 参考記事

https://qiita.com/kai_kou/items/feca8974f3967a285ff4

https://qiita.com/oskamathis/items/c374138635eb0012b119

https://dev.classmethod.jp/articles/api-document-with-api-blueprint/