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

More than 3 years have passed since last update.

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 docsdocs/以下にあるマークダウンを変換して

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

他にも色々あったりするけれど、ここらへんを知っていれば

色々とカスタマイズできそうです。