まえがき

みなさんサーバーのAPI仕様書、どのように管理してますか？
ConfluenceとかDropboxとかで保管したりしている人やプロジェクトも多々あると思いますが、こんな問題抱えていませんか？

メンテナンスされない
仕様書があいまいで結局よくわからない
仕様書を書いた後にモックサーバー作るのが面倒

仕様書くだけで綺麗なドキュメントになって、モックサーバーまで起動できたら上のような問題が解消されるのではないでしょうか。

開発フロー

上のような図でいうと、特に決まったルールもないAPI仕様書を書いて、それにそってモックサーバーを作ってクライアント側のエンジニアも作業できるような環境を整えてから実サーバーの作成といった流れで開発が進む場合を考えます。

冒頭にも書いたのですが、なにかしらルールを設けてAPI仕様書を書いたところで、作った仕様自体が曖昧だったり、モックサーバー作ってるうちに足りない、仕様書と違う、なんて状況になると、時間をかけて仕様書も直してモックもその通り作れるようなプロジェクトならいいですが、実際のところAPI仕様書がメンテされなくなるか、仕様書を書き直したところでAPIの曖昧さは残ったりします。

そんな中、決まったルールでAPI仕様書を書いたらコマンド1発でモックサーバーが作成でき、見やすいドキュメントまで生成することができる仕様・ライブラリがあるわけです。

API Blueprint

APIの仕様を書くための仕様で、API Blueprint(以下apibと略します)というものがあります。
この仕様の通りにapibを書いていけば、関連するライブラリを使って、ドキュメントを生成したり、モックサーバーを起動することができます。

ライブラリは様々ありますが、今回はaglioとdrakovについて書いていきます。他のツールについては、主にこちらに書かれているので、ユースケースに応じて調べてみてください。ちなみに、ドキュメントを生成するツールはrenderers、モックサーバーを起動するツールはmock serversと書かれています。

aglio

aglioはrenderersに分類される、ドキュメントを生成するツールです。ちなみにイタリア語で「にんにく」らしいですが、なぜこんなにおいしいが臭い食材を命名したのかはよくわかりません。

コマンドは $ aglio -i xxx.apib -o xxx.html のようにしてドキュメントを生成したり、 $ aglio -i xxx.apib -s -p 8080 のようにしてドキュメントのサーバーを起動したりできます。

--compileオプションをつけると、分割した複数のapibファイルを1つのapibファイルにまとめることができます、これに関してはdrakovの説明の後に使いどころを書きます。

drakov

drakovはmock serversに分類される、モックサーバーを起動するツールです。ちなみにスロバキア語で「ドラゴン」らしいです。

コマンドは$ drakovコマンドでモックサーバーを起動するのですが、起動条件の指定は.drakovrcファイルか、コマンドライン引数で指定します。.drakovrcファイルを作ると全てのコマンドライン引数が無視されます。

ファイルの分割

実際にapibを書いているとすぐに思うのは、仕様書って莫大な量になるので1つのファイルに書いていると管理が大変です。なので、aglioではのようにしてファイルを分割することができます。

しかしこれ、drakovは認識してくれないんです。なので1つのapibファイルしかモックサーバーを起動できない感じになってきました。

そこでaglioの--compileオプションなんですが、これを使うと複数に分けて管理していたapibから1つのapibファイルを出力することができるので、どんなにファイルを分割してもaglioがまとめてくれる範囲内でモックを起動することができます。

さいごに

正直なところ、apibの仕様がかなり膨大なので全部覚えるのは大変なんですが、基本的なところだけ覚えればかなり運用まで考慮した効率的な開発ができると思います。

ぜひ試して見てください。