St_Hakky’s blog

Data Science / Human Resources / Web Applicationについて書きます

「API Blueprint」を使ってWeb APIの仕様書を書くことになったのでその時に調べたこととかをまとめる

こんにちは。

APIの仕様書をチームで書いて、その仕様書を元にガリガリ実装していくことになったのですが、今回「API Blueprint」というものを初めて使ったので、その時に調べたこととか参考になったサイトとかをまとめます。

〇本家のサイト

本家のサイトは以下から見れます。

API Blueprintとは

API Blueprintは、APIドキュメント管理ツールです。なぜこんなツールが必要かということなのですが、

  • 開発者が同じフォーマットでドキュメントは書いたほうがいい
  • Gitで管理したい
  • mockサーバーをドキュメントから立ち上げるなどして、フロントの開発が止まるといったことを防ぎたい
  • ドキュメントとコードが乖離しないようにしたい
  • Markdownとかでかけるといいな

などなどといった欲求があるからです。以下のサイトが非常にわかりやすくて参考になりました。

dev.classmethod.jp

〇他のAPIドキュメント管理ツールとの比較

API Blueprint以外にも、swaggerなどといったツールがありますが、それについては以下の資料がわかりやすくまとまっていました。

API Blueprint周りのツールについて

■aglio

これを使うと、API BlueprintをHTMLに変換してくれます。

api-blueprint-preview/language-api-blueprint

Atomを使っているユーザーなら入れておきたいプラグインです。api-blueprint-previewはリアルタイムでプレビューを出してくれます(自分は結局、gulpでmarkdownからhtmlに変換して、自動更新をさせるようにしたので、これは途中から使わなかったですが)。

api-mock

API Blueprint形式でかいたドキュメントから、モックサーバーを自動で立ち上げてくれるツールです。

しかし、このインストールで結構はまりました、、、汗(それは後述します)

■Dredd

API Blueprintのドキュメントを元に実装をテストしてくれるツールです。これにより、ドキュメントとコードの乖離を防ぐことができます。

■gulp

Node.jsをベースとしたビルドツールです。これであらゆるタスクを自動的に実行させることができます

API Blueprintとは直接関係はないですが、これによりMarkdownを更新した時に自動でHTMLファイルに変換させるみたいなことができるようになり、便利です。

■gulp-aglio

これは、aglioをgulpで使い、Blueprintで書かれたMarkdownをHTMLに変換してくれるツールです。跡で紹介しますが、これを使って、ファイルの更新を取得→自動的にMarkdownからHTMLに変換という処理をgulpで行うことができます。

API Blueprintを使うならしておきたい設定

以下のサイトの設定たちが最高にcoolだったので、これを参考に環境構築や設定は行いました。

自分は、こちらを参考にして、これに追加でapi-mockもいれて、自動でモックサーバーも起動できるようにしました。

api-mockを使う時の注意点

一番最初の注意点は、私はWindowsで開発をしていたのですが、api-mockに渡すMarkdownのファイルの改行コードがLFでないとエラーがでます(笑)。

これは、protagonistっていうAPI blueprintのParserが原因のようです。

また、nodeのバージョンが5か6だと、api-mockが使用しているprotagonistのインストールでこけます(自分はこけました)。なので、nodeのバージョンを4に落として開発しています笑(つらい)。5でも動いたよっていう情報もあったんですが、自分は試してません。

上の資料を読んでいろいろ試していたら一通り使えるようになったので、とりあえずおっけーかなと。
それでは。