API 設計ドキュメントをGitHubのプルリクでレビューしつつ Apiary みたいに使うには

API 設計ドキュメントを GitHub のプルリクでコードレビューしつつ Apiary みたい使う方法を考えました。
既存ツールでは、Apiary が良さそうだったのですが、次のような問題がありました。

• GitHub 連携すれば diff が見られるらしいが、連携の制約が満たせなかった
• リアルタイムプレビューが重い
• 1ファイル管理がつらい

そこで以下の機能を手元で実現できるようにしました。

• API Blueprint フォーマットのマークダウン形式のファイルを Group 単位で別ファイルで編集できるようにする
• Group 単位のマークダウン形式の API 仕様を 1ファイルにまとめる
• API Blueprint フォーマットのマークダウン形式のファイルから HTML 形式の API 仕様書を生成する
• 編集中にリアルタイムプレビューできる

次のような利用イメージです。
apidocs/templates/layout.md に以下のようなレイアウトを作成し、

FORMAT: 1A
HOST: http://polls.apiblueprint.org/

<% include aaApi.md %>

apidocs/templates/aaApi.md に aa API の仕様を API Blueprint フォーマットのマークダウンで記載します。
以下のようなディレクトリレイアウトを想定しています。

~/repos/api-review-tool
% tree apidocs
.
├── published
│   └── index.html
│   └── index.md
└── templates
    ├── layout.md
    └── aaApi.md

編集中は、gulp のデフォルトタスクで http://localhost:8088 でリアルタイムプレビューできます。
編集がおわったら、以下のコマンドを実行します。

gulp publish

すると、apidocs/published/index.html と apidocs/published/index.md が生成されます。
生成された結果を apiary のテキストエリアに貼り付けたり、api-mock でモックサーバーを立てたりと利用できます。

作り方

必要なライブラリをインストールします。

npm install -g aglio
npm install gulp --save-dev
npm install gulp-aglio --save-dev
npm install browser-sync --save-dev
npm install rimraf --save-dev
npm install gulp-ejs --save-dev
npm install gulp-rename --save-dev

gulpfile.js を作成します。

.javascript

"use strict";

var gulp        = require('gulp');
var aglio       = require('gulp-aglio');
var browserSync = require('browser-sync');
var rimraf      = require('rimraf');
var ejs         = require('gulp-ejs');
var rename      = require('gulp-rename');

var reload = browserSync.reload;

var TEMPLATE_FILES = ['apidocs/templates/**/*.md'];
var LAYOUT_FILE = 'apidocs/templates/layout.md'
var PUBLISHED_DIR = 'apidocs/published';

gulp.task('combine', function(){
  return gulp.src(LAYOUT_FILE)
    .pipe(ejs({},{ ext: '.md' }))
    .pipe(rename('index.md'))
    .pipe(gulp.dest(PUBLISHED_DIR));
});

gulp.task('generate-api-docs', ['combine'], function() {
  return gulp.src(PUBLISHED_DIR + '/index.md')
    .pipe(aglio({template: 'default'}))
    .pipe(gulp.dest(PUBLISHED_DIR));
});

gulp.task('watch', function () {
  gulp.watch(TEMPLATE_FILES, ['generate-api-docs', reload]);
});

gulp.task('browserSync', function() {
  browserSync({
    logConnections: true,
    logFileChanges: true,
    notify: true,
    port: 8088,
    open: false,
    server: {
      baseDir: PUBLISHED_DIR
    }
  });
});

gulp.task('clean', function(cb) {
  rimraf(PUBLISHED_DIR, cb);
});

gulp.task('publish', ['clean', 'generate-api-docs']);
gulp.task('default', ['generate-api-docs', 'watch', 'browserSync']);

あとは上に書いたように gulp のデフォルトタスクを実行して開発、gulp publish でドキュメントを生成します。

追記

aglio に include 機能があるようです。成果物として1ファイルのマークダウンファイルがいらないなら、aglio の include 機能を使うのもよいと思います。

• https://github.com/danielgtaylor/aglio#including-files