api blueprintとaglioを利用してAPI仕様書を作成する

概要

Web APIの開発をするのにとりあえずモックを作成してフロントエンドからアクセスできるようにしたくて、どうしようかなと悩んでたらAPI Blueprintなるものを知ったので、試してみました。
今回はAPIドキュメントを手間なくまとめるツールのご紹介です。

api blueprint
https://apiblueprint.org/

こちらの記事を参考にさせてもらいました。感謝！

API BlueprintとdrakovとdreddでAPIドキュメントを書きつつモックサーバを立ててさらにテストを走らせる
https://arata.hatenadiary.com/entry/2018/03/22/204723

今回構築した環境をGitHubにUPしていますので、ご参考ください。
https://github.com/kai-kou/api-blueprint-use-aglio

環境構築

いつもDockerを利用しているので、Docker環境を用意します。
こちらは趣味なので、ローカルでもOKです。
node.jsが利用できるようにイメージを指定します。

> mkdir 任意のディレクトリ
> cd 任意のディレクトリ
> touch Dockerfile
> touch docker-compose.yml

FROM node:latest

WORKDIR /projects

version: '3'

services:
  api:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ".:/projects"
    tty: true

> docker-compose up -d
> docker-compose exec api bash

ドキュメント作成できるようにする

api blueprintの仕様で記述したmarkdownをHTMLに変換してくれるツールがいくつかあるようですが、ここではaglioを利用してみます。

danielgtaylor/aglio
https://github.com/danielgtaylor/aglio

私の環境だとnpm install -g aglio でエラーが出たため、--unsafe-perm オプションを付けてインストールしました。

> npm install -g aglio --unsafe-perm

参考)can't install aglio on linux #340
https://github.com/danielgtaylor/aglio/issues/340

インストールできたか確認します。

> aglio
Usage: aglio [options] -i infile [-o outfile -s]

Options:
  -i, --input           Input file
  -o, --output          Output file
  -t, --theme           Theme name or layout file           [default: "default"]
(略)

インストールできました。

さっそく、API仕様を記述してみます。

> mkdir md
> mkdir docs
> touch md/sample.md

テキストを返す場合、Response 定義の後に、改行+8スペースか2タブを含める必要があるみたいですね。言語仕様を確認しないとわからないですね^^

# GET /message
+ Response 200 (text/plain)

        Hello World!

さっそくHTMLを出力してみます。-i でmdファイルを指定、-o で出力ファイルを指定です。両方必須となっています。

> aglio -i md/sample.md -o docs/sample.html

これで、htmlファイルが出力されたので、ブラウザで確認してみます。

いい感じに出力されていますね。

パラメータ指定するとテーマも選べるみたいです。

> aglio --theme-variables slate -i md/sample.md -o docs/sample.html

いいですね〜(歓喜

mdファイルを変更する度にコマンドを叩くのは面倒なので、プレビューオプションを利用します。

> aglio --theme-variables slate -i md/sample.md -s -h 0.0.0.0

Server started on http://0.0.0.0:3000/
Rendering md/sample.md

Dockerを利用している場合、ホスト名を-h 0.0.0.0 で指定します。
ポートも変更したい場合は、-p xxxx で指定できます。

ホストからブラウザでアクセスしてみます。

> open http://localhost:3000/

はい。

mdファイルを変更して保存すると、自動でブラウザを再読込してくれます。偉い！

Socket connected
Refresh web page in browser
Updated md/sample.md
Rendering md/sample.md
Refresh web page in browser

これで、設計中はプレビューモードで作業して、完了したらHTML出力で効率よく設計ができそうです。

参考

api blueprint
https://apiblueprint.org/

API BlueprintとdrakovとdreddでAPIドキュメントを書きつつモックサーバを立ててさらにテストを走らせる
https://arata.hatenadiary.com/entry/2018/03/22/204723

danielgtaylor/aglio
https://github.com/danielgtaylor/aglio