APIドキュメントを生成するためのMarkdown拡張API BluePrintとその周辺のライブラリ

API Blueprint(以下Blueprint) は
MarkdownファイルからAPIドキュメントやサンプルデータになる
JSONを生成する仕様。

一旦決められたフォーマットのJSONに吐き出すので、
それを中心に入出力のライブラリが色々あったりする。

Blueprintのパーサー

MarkdownからJSONを出力するために
Snow Crashというライブラリを利用する。

後に書くものは大体このSow Crashを利用するので詳細は省略。

BlueprintからAPIドキュメントHTMLを生成する

Blueprintを上手く扱うために、
色々なライブラリが用意されている。

aglioはBlueprintから表示用htmlを用意してくれるライブラリ。

$ npm install -g aglio

# output.htmlにファイル出力
$ aglio -i input.md -o output.html

# デフォルトの http://localhost:3000 でアクセスできるAPIドキュメントサーバー起動
$ aglio -i input.md —server

gulp-aglio

gulpのタスクで取り扱いたいときは gulp-aglioを使う。

gulpfile.js

var aglio = require('gulp-aglio');
gulp.task('docs', function() {
  gulp.src("./docs/*.md")
    .pipe(aglio({template: 'default'}))
    .pipe(gulp.dest("public")); });

gulp docsでdocs/以下にあるマークダウンを変換して
public/以下に置くことが出来る。

API Blueprintからモックサーバを立てる

https://github.com/localmed/api-mock を使うとBlueprintを元に
APIのモックサーバーを生成してくれます。

$ npm install -g api-mock

$ api-mock input.md
info:    Enabled Cross-Origin-Resource-Sharing (CORS)
info:         Allow-Origin: *
info:         Allow-Methods: GET, PUT, POST, PATCH, DELETE, TRACE, OPTIONS
info:         Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization, Referer, Prefer
info:    Listening on port 3000

他にも色々あったりするけれど、ここらへんを知っていれば
色々とカスタマイズできそうです。