こんにちは。
APIの仕様書をチームで書いて、その仕様書を元にガリガリ実装していくことになったのですが、今回「API Blueprint」というものを初めて使ったので、その時に調べたこととか参考になったサイトとかをまとめます。
〇本家のサイト
本家のサイトは以下から見れます。
〇API Blueprintとは
API Blueprintは、APIドキュメント管理ツールです。なぜこんなツールが必要かということなのですが、
- 開発者が同じフォーマットでドキュメントは書いたほうがいい
- Gitで管理したい
- mockサーバーをドキュメントから立ち上げるなどして、フロントの開発が止まるといったことを防ぎたい
- ドキュメントとコードが乖離しないようにしたい
- Markdownとかでかけるといいな
などなどといった欲求があるからです。以下のサイトが非常にわかりやすくて参考になりました。
〇API Blueprint周りのツールについて
■aglio
これを使うと、API BlueprintをHTMLに変換してくれます。
■api-blueprint-preview/language-api-blueprint
Atomを使っているユーザーなら入れておきたいプラグインです。api-blueprint-previewはリアルタイムでプレビューを出してくれます(自分は結局、gulpでmarkdownからhtmlに変換して、自動更新をさせるようにしたので、これは途中から使わなかったですが)。
■Dredd
API Blueprintのドキュメントを元に実装をテストしてくれるツールです。これにより、ドキュメントとコードの乖離を防ぐことができます。
■gulp
Node.jsをベースとしたビルドツールです。これであらゆるタスクを自動的に実行させることができます。
API Blueprintとは直接関係はないですが、これによりMarkdownを更新した時に自動でHTMLファイルに変換させるみたいなことができるようになり、便利です。
〇API Blueprintを使うならしておきたい設定
以下のサイトの設定たちが最高にcoolだったので、これを参考に環境構築や設定は行いました。
〇api-mockを使う時の注意点
一番最初の注意点は、私はWindowsで開発をしていたのですが、api-mockに渡すMarkdownのファイルの改行コードがLFでないとエラーがでます(笑)。
これは、protagonistっていうAPI blueprintのParserが原因のようです。
また、nodeのバージョンが5か6だと、api-mockが使用しているprotagonistのインストールでこけます(自分はこけました)。なので、nodeのバージョンを4に落として開発しています笑(つらい)。5でも動いたよっていう情報もあったんですが、自分は試してません。
上の資料を読んでいろいろ試していたら一通り使えるようになったので、とりあえずおっけーかなと。
それでは。