interprism's blog

インタープリズム株式会社の開発者ブログです。

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

この投稿は インタープリズム的「俺達私達の進捗を上げる25個前後のTips」 Advent Calendar 2015 - Qiitaの11日目 の記事です。

こんにちは、imamotoです。

AdventCalendarに二度目の登場です。

今日はAPI Blueprintという記法のMarkdownをgulp-aglioというツールでHTMLのAPIドキュメントページにパースしていきます。

簡単な手順ですごくいい感じのドキュメントページが作れますので是非活用してみてください!

きっかけ

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

やったこと

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

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

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

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

(1) nodeをインストール

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

brew install node

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

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

mkdir ~/apiblueprint
cd ~/apiblueprint
npm init

(3) 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:interprism:20151205002341p:plain

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

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

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

インタープリズム的「俺達私達の進捗を上げる25個前後のTips」 Advent Calendar 2015 - Qiita12日目の記事

インタープリズムのページ

PAGE TOP