API Blueprint
API Blueprintは、APIドキュメントを記述するためのMarkdown拡張です。おおくのツールが公開されており、htmlに変換したり、mock-serverを立てたりできます。
また、Markdown likeなのでそのままでもGithub等で読めます。便利！
つまり、ルールに従ってMarkdownを書くと、モックやhtmlが出来上がる ということです。最高ですね。
他の方法との比較
公式サイトには、他の方法と比較した時の以下の様な利点が挙げられています。
API Blueprint vs. DIY
車輪の再発明をしてる暇があったらAPI開発しようぜ！
API Blueprintは君にヤバいツールを提供する。それを使ってみんなと議論すれば、あとはドキュメントやテスト、Railsのコードすら自動生成できるんだ。
API Blueprint vs. JSON
JSONって人間が書くものじゃないでしょ？ そんなのプログラムに任せればいいんだよ。
君が書いたドキュメント、来年になったら誰が管理するの? API Blueprintなら誰だって管理できるんだ。デザイナやコピーライターでもね。
API Blueprint vs. Google Docs
コードは進化し、分岐して行く。バージョンが付けられ、テストされる。そしてそれはコードだけでなく、ドキュメントだってそうあるべきだ。
API Blueprintは、リポジトリの中でコードと共存する。そして、コードと同じライフサイクルを持ち、君の大好きなCIやワークフローに乗せることができるんだ。
とりあえずはじめよう
Apiaryというサービスがあります。
Blueprintを書くと、モックサーバーとドキュメントのサイトが生成される超絶便利なサービスです。
しかもなんと、Githubと連携して既存のリポジトリに追加することができます。
それ以外にも、わざわざcurlを叩かなくてもサービス上からレスポンスを確認できたりと、めちゃくちゃ便利です。
ローカルで使いたい
node環境で使いたい
ドキュメント生成・プレビュー
$ npm install -g aglio
$ aglio -i api.md -o api.html # convert to html
$ aglio -i api.md --server # preview server
プレビュー用のサーバーは、ファイルを更新するとリロードしてくれたりと、結構高機能です。
gulpを使いたい場合はこんな感じ。
$ npm install aglio-gulp
var aglio = require('gulp-aglio');
gulp.task('docs', function () {
gulp.src('_docs/*.md')
.pipe(aglio({ template: 'default' }))
.pipe(gulp.dest('docs'));
});
モックサーバー
$ npm install -g api-mock
$ api-mock api.md
こちらはファイルを変更すると、サーバーを立ち上げ直さないと変更が反映されません。
モックサーバーを利用しながらAPIを変更するということは無いと思うので大丈夫だと思いますが。
その他の環境で使いたい
公式サイトに、ツールのリストがあるので、そちらを参照するとよいでしょう。
Blueprintの書き方
ざっくり書こうと思ってたんですが、思ったよりも柔軟でいろいろと複雑だったのでそのうち別の記事を書きます。
まとめ
あなたもいますぐ、API Blueprintでハッピードキュメントライフを送りましょう！