API Blueprint を利用して Markdown 形式で API 仕様書を作成する

WebAPI の仕様書を Markdown 形式で作成するための拡張言語として、API Blueprint というものが作られている。今回はコレを用いて、Markdown 形式で API 仕様書を作り、HTML 形式で出力してみる。

API Blueprint とは

API Blueprint は、Markdown 拡張記法のことで、これ自体は何かのツールというワケではない。

公式サイトでも紹介されているが、API Blueprint の記法で書かれた Markdown ファイルをアレコレ活用できる周辺ツールが色々ある、という関係になっている。

今回はこの中で、Aglio というツールを使って、HTML 形式で API 仕様書を出力してみようと思う。

他にも、API Blueprint の Markdown ファイルをベースにモックサーバを構築してくれる API-Mock などのツールもあるので、適宜調べて活用して欲しい。

API Blueprint を書いてみる

まずはサンプルコードをそのまま利用してみる。

# GET /message

- Response 200 (text/plain)

        Hello World!

「Hello World!」部分は8スペースであること。

記法のことは一旦後回しにして、HTML 形式で出力できる環境を先に作ろう。

Aglio を使って HTML に出力する

Markdown ファイルを HTML 形式に出力するには、Aglio というツールを使う。npm パッケージとしてインストールするので、適当な作業ディレクトリを作成しよう。

$ mkdir api-blueprint-practice && cd $_
$ npm init -y
$ npm install -S aglio
# aglio@2.3.0 がインストールできた

グローバルインストールを避けるためにこのようにしたが、グローバルインストールして良ければ npm i -g aglio で良い。

次に、この作業ディレクトリに先程の Markdown ファイルを保存する。今回は example.md という名前で保存したことにする。

用意ができたら、以下のようにプレビューしてみる。

$ $(npm bin)/aglio -i example.md --server
Server started on http://127.0.0.1:3000/
Rendering example.md

このように表示されたら、上手くパースできている。ブラウザで http://127.0.0.1:3000/ にアクセスすると、今作った example.md が HTML 形式で表示されているはずだ。

プレビューして問題なければ、以下のように叩いて example.html としてファイルに出力できる。

$(npm bin)/aglio -i example.md -o example.html

コレでひとまず、API Blueprint を作って出力するための環境ができた。

記法が結構難解…

さて、環境構築ができたら、API Blueprint の記法を覚えてガリガリ書いていこう…と思うのだが、API Blueprint の記法は結構複雑で分かりづらい。

以下のサイトあたりを見ながら頑張って記法を押さえていこう。

以上。最後投げやりな感じだけど…;;