API Blueprintとgulp-aglioでいい感じのAPIドキュメントページを作成
きっかけ
やったこと
APIドキュメントの作成は以下の手順で行いました。
1. gulp-aglioをインストール
gulp-aglioはAPI 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コマンドのシンボリックリンクが張られているか確認してください。
そのディレクトリのパスを通せば使えると思います(自分はそれで少しハマりました)。
作業ディレクトリ(~/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が作成されました。 ブラウザで開くと以下のようないい感じのドキュメントになります。
なお、API Blueprint記法の具体的な記述方法は公式ページやGithub上の公式サンプルを参考にしてください。
かなり綺麗にカスタマイズできると思います!
それでは素敵なAPIドキュメントライフを!!