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 を作成します。
"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 機能を使うのもよいと思います。