はじめに
業務でAPIに関するところに携わることになりました。
昔ながらのやり方だと、仕様書=Excelということになりますが
「仕様書もコード化をしないと!」と考え、API Blueprintを使い
API仕様書を作ることにしました。
API Blueprint | API Blueprint
自分だけノウハウを持っていても、もったいないので
ブログに書いてやり方を広めて行きたいと思います。
API仕様書をAPI Blueprintで書くメリット
新しいものを導入する場合、チームの合意が得られないと導入できません。
その手助けになるようメリットを列挙していきます。
・マークダウン形式にすることにより、仕様書のレビューがしやすくなる。
Excelの場合だと、ファイル単位でバージョン管理できますが
ファイルの中身まで差分を見れません。
そのため、履歴シートを作り、修正したところを赤文字にしたりと
かなり手間がかかります。これは作業効率が落ちる要因となります。
マークダウンにすることにより、Gitで見た場合
詳細に差分を確認することができレビューしやすい状態にできます。
・HTML出力することにより、ブラウザで仕様書を確認できる。
わざわざExcelのアプリを立ち上げて仕様書を見るというのは辛いです。
Googleスプレッドシートもありますが、Googleアカウントではない場合
使うことができません。
なので、HTMLファイルとして出力することにより誰でも簡単に
仕様書を見ることができます。
・脱Excelをすることができる。
WindowsでもMacでも仕様書が大きくなるにつれ、Excelが重くなり
よく落ちることに見舞われないでしょうか?それを無くすことができます。
パッと思いつく限りではこんな感じでしょうか。
環境
- maxOS Sierra
- nodebrew
- 筆者、gulp, Node.js経験ほとんどなし
前提条件
やり方
サンプルで作ったものは、GitHubに上げてあります。
github.com
Nodeライブラリのインストール
各種ライブラリを使うため、インストールを行います。
$ npm install
上記を実行すると「node_modules」に必要なライブラリが入ります。
こうしておくことにより、プロジェクト単位でライブラリ管理ができます。
gulpの実行
API仕様書を更新した際、手動でHTML生成するのは大変なので
「gulp-aglio」と「browser-sync」を使い、自動生成されるようにしました。
起動の仕方はターミナルで以下のコマンドを実行するだけでOK。
$ node_modules/.bin/gulp
そうすると起動時にログが出力され動いている状態となります。
[14:53:32] Y_Fujikawa:sample-api-document git:(master) $ gulp
[15:23:36] Using gulpfile ~/project/sample-api-document/gulpfile.js
[15:23:36] Starting 'combine'...
[15:23:36] Starting 'watch'...
[15:23:36] Finished 'watch' after 9.58 ms
[15:23:36] Starting 'browserSync'...
[15:23:36] Finished 'browserSync' after 89 ms
[15:23:36] Finished 'combine' after 137 ms
[15:23:36] Starting 'generate-api-docs'...
[BS] Access URLs:
----------------------------------------
Local: http://localhost:8088
External: http://XXX.XXX.XXX.XXX:8088
----------------------------------------
UI: http://localhost:3001
UI External: http://XXX.XXX.XXX.XXX:3001
----------------------------------------
[BS] Serving files from: ./
[15:23:38] Finished 'generate-api-docs' after 1.49 s
[15:23:38] Starting 'default'...
[15:23:38] Finished 'default' after 61 μs
この状態でマークダウンで仕様書を更新すると、自動的にgulpが実行され
API仕様書がマークダウンファイルとHTMLファイルで作成されます。
モックサーバーを起動して、APIの戻り値を確認する
チームメンバーから「モックサーバーがあると良い」という話を受けました。
モックサーバーのために時間をかけて、サーバーを用意するのもどうかと思い
探していたところ、API Blueprintにはモックサーバーをローカルマシンに
起動させるライブラリをがあるようです。
それが「drakov」というものでした。
他にもいろいろあったのですが、今回はこれを使うようにしました。
実行の仕方は以下の通り。
なお、オプションで「watch」はファイル変更時のでき
「public」はローカルマシン以外からアクセスできるようにするものです。
node_modules/.bin/drakov -f "index.md" --watch --public
実行をするとログが出力され、起動している状態になります。
[INFO] No configuration files found
[INFO] Loading configuration from CLI
DRAKOV STARTED
[LOG] Setup Route: POST /v1/user/list ユーザリスト取得
[LOG] Setup Route: POST /v1/admin/item/list 商品リスト取得
Drakov 1.0.3 Listening on port 3000
PUBLIC MODE running publicly
FILE SPY ACTIVE
想定した、ものが返ってくるか確認するためcurlでAPIを実行してみます。
[15:38:17] Y_Fujikawa:~ $ curl -XPOST -H "x-sample-api-access-token: xx" -H "Content-Type: application/json" http://localhost:3000/v1/admin/item/list
{
"result_code": "0",
"item_list": [
{
"id": 9876,
"name": "りんご",
"stock": 100
},
{
"id": 8765,
"name": "バナナ",
"stock": 0
}
]
}%
おぉ、問題なくAPIが返ってきました。
GitHub Pagesを使ってAPIドキュメントを表示させる
HTMLファイルまで出力できましたが、いちいちファイルを開いてみるのは
ナンセンスだと思い、サーバーでも用意しようかな?と考えました。
しかし、わざわざこのためだけにドキュメントサーバーを用意するのは
手間だったので、GitHub Pagesを使うことにしました。
やり方は以下の通り。


そうすると、以下のURLでアクセスすることができます。
https://y-fujikawa.github.io/sample-api-document/

まとめ
「結局、Excelで管理していたのね・・・」ということがあり
今回、API BlueprintでAPI仕様書を作成する方法を模索して、プロジェクトに取り入れることができました。
API Blueprint自体はだいぶ前からありますが、実際にプロジェクトで使っているという
話は聞かないので、これを機に「バリバリ使っています!」という話を聞ければと思います。
また「Excelからマークダウンにして、バージョン管理しよう!」ということに
発展するプロジェクトに少しでも役立てれればと思います。
参考サイト
API Blueprint | API Blueprint
【API Blueprintの使い方】Web APIの仕様書を書く・読む・実行する | Developers.IO
aglioでAPI Blueprintを使ったドキュメント作成環境をローカルに構築する - dackdive's blog
aglioとdrakovでAPI仕様書とMockを生成する手順 | takemikami's note