はてなブログ

IT業界にひっそり生息しています。

API Blueprintとgulp-aglioでいい感じのAPIドキュメントページを作成

きっかけ

  • 現在関わっているWebサービスの各種APIをまとめたドキュメントを作りたかった
  • いい感じのHTMLページにして、なるべく簡単に作りたかった
  • Web上のサービスではなくローカルで作りたかった

やったこと

APIドキュメントの作成は以下の手順で行いました。

1. gulp-aglioをインストール

gulp-aglioAPI Blueprint(後述)で書かれたMarkdownをHTMLにパースするgulpプラグインです。

自分がmacにインストールした手順は以下の通りです。

(1) nodeをインストール

Homebrewを使ってnodeをインストールします。

brew install node

(2) gulpをグローバルインストール

npmでgulpをグローバルインストールします。

npm install -g gulp

また、インストールは以下のコマンドで確認します。

gulp -v

コマンドが使えない場合は ~/.node/bin または ~/usr/local/bin のどちらにgulpコマンドのシンボリックリンクが張られているか確認してください。

そのディレクトリのパスを通せば使えると思います(自分はそれで少しハマりました)。

(3) 作業ディレクトリにpackage.json作成

作業ディレクトリ(~/apiblueprintとする)を作成・移動し、その直下にpackage.jsonを作成します。

mkdir ~/apiblueprint
cd ~/apiblueprint
npm init

(4) gulpとgulp-aglioをローカルインストール

gulpとgulp-aglioを作業ディレクトリにローカルインストールしてください。

npm install gulp gulp-aglio --save-dev

--save-devオプションを付けてインストールすると別の環境でも同じバージョンのgulpプラグインを簡単に入れられます。

その場合はpackage.json を共有してnpm init を実行するだけでインストールできます。

2. API Blueprint記法でAPIの一覧を書く

API Blueprintとは特定のルールでAPIの詳細を記述するMarkdown記法です。

また、公式ではSnow CrashというAPI Blueprint用のパーサーを使ってAPIの概要をJSON形式のデータで取得する方法が紹介されています。

しかしgulp-aglioを使う場合はSnow Crashを個別にインストールする必要はないので今回は省略します。

作業ディレクトリに _docs ディレクトリを作成し、API Blueprint記法で書いたMarkdownファイルを拡張子 .md で保存します。

また、パースされたHTMLの出力先として docs ディレクトリも作成しておきます。

3. gulpfile.jsを作成

作業ディレクトリ直下に gulpfile.js というファイルを作成し、以下のようにdocsという名前のタスクを記述します。

var gulp = require('gulp');
var aglio = require('gulp-aglio');
gulp.task('docs', function () {
    gulp.src('_docs/*.md')
        .pipe(aglio({ template: 'default' }))
        .pipe(gulp.dest('docs'));
});
4. docsタスクを実行してHTMLのAPIドキュメントを作成

docsタスクを実行します。

gulp docs

_docsディレクトリ配下の.mdファイルがパースされて、docsディレクトリにパース後のHTMLファイルが出力されれば成功です。

実際にやってみる

公式にあるサンプルをそのまま拝借して、_docs/sample.mdを作成します。

# Message [/messages/{id}]

## Retrieve Message [GET]
+ Response 200 (text/plain)

        Hello World!

## Delete Message [DELETE]
+ Response 204

docsタスクを実行すると、docs/sample.htmlが作成されました。 ブラウザで開くと以下のようないい感じのドキュメントになります。

f:id:imamoto:20150118032617p:plain

なお、API Blueprint記法の具体的な記述方法は公式ページGithub上の公式サンプルを参考にしてください。

かなり綺麗にカスタマイズできると思います!

それでは素敵なAPIドキュメントライフを!!