WEB EGG

APIドキュメントでAPIサーバをテストする

December 05, 2015 · 8 min read

SPAやハイブリットアプリを仕事でも趣味で作っているので、APIサーバを実装する機会が増えています。
手軽にしっかりしたドキュメントを書けて、かつ実装とドキュメントの整合性を保つのってコスト高いな…。と悩んでいます。

Web APIのドキュメントといえば、SwaggerやJSON-Schemaあたりが有名かと思います。
例えばQiitaのAPIv2はJSON-Schemaを使用して書かれています。

今回はそれらとは違うAPI Blueprintというツールを使用してAPIドキュメントを作成し、そのAPIドキュメントを自動テストとして実行できるDreddというツールを使用し、
APIドキュメントを書いたら、APIサーバのテストもできる 方法を残します。

ついでにAPI Blueprint形式のドキュメントをホスティングしてくれるApiaryとGithubを連携し、masterにマージされたら公開されているAPIドキュメントも最新になるというのもやってみます。

今回作成したデモは Leko/godemo にて公開しています。
今回作成したAPIドキュメントはこちらにて公開してます。

今回はデモとしてTODOアプリ用のAPIを作ってみます。

GET /api/todos
- 自分のTODO一覧を取得する
- completedパラメータを与えるとその状態のTODOのみ取得する。指定がなければどちらも取得する
POST /api/todos
- TODOを作成する

という2つの機能を持つAPIサーバのドキュメントを書きます。

詳しい記述方法についてはAPI Blueprintの仕様を御覧ください。
だいたいこんな感じになるかと思います

書いたら、プロジェクト直下にapiary.apibというファイル名で保存しておきます。
ファイルの内容はMarkdownですが、API Blueprintというフォーマットで記述しているため拡張子はapibです。

今回はGoの話ではないですし、先ほどの仕様の通りに作っただけなのでさっくり済ませます。

Apiaryは、API Blueprintで書かれたAPIドキュメントをもとに

などなどをまるっと生成してくれるサービスです。

オレオレドキュメントで作成・管理はかなり手間が大きいと思います。
playgroundをいちいち作ったり、サンプルコードで複数言語に対応したり、見やすいドキュメントにしたり、書き手として一貫したドキュメントにすること、など実装のコストもメンテナンスのコストも高くつきます。

そんなつらみをApiaryが助けてくれます。
保守コストを抑えつつ、見る人にとってより使いやすい、読みやすいドキュメントを作るための手段の一つだと思います。

早速テストしてみます。テストにはApiaryが提供するdreddというツールを使用します。
導入の注意点として、Dredd周りのツールがNode4や5に対応しておらず、dreddを入れるためにはnode0.10系が必要になります。 古い…。

Error compiling on Mac OS X 10.10.5 #287
Support for node v4.X #292

npm i -g dredd

テストの環境のセットアップは、ApiaryのTestsタブに記述されています。

Goのサーバを起動しておき、書かれているとおりにコマンドを実行します。

dredd init # 省略,対話CLIがあります
dredd

↑こんな感じになります。
さらに、 Apiaryの言うとおりにdredd initしておくと、そのテストの通知結果が集約される ようになっています。

立てておいたGoのサーバに対してHTTPリクエストが飛び、どんなレスポンスが返ってきたかをテストしてくれます。
これで実装が変わっても、ドキュメントが変わってもコマンド一つで整合性を確認できます。

リクエストと対応するレスポンスのパターンを書けば書くほどテストケースが増えるので、
ドキュメントをしっかり書くことがテストのクオリティ向上、ひいてはプロダクトの質向上に繋がる ところが、ドキュメントを書くモチベに繋がるなと感じます。

反映漏れや食い違いを起こさないために、
APIドキュメントをGitで管理して、GithubのmasterにpushされたらApiaryのドキュメントに自動反映されるようにします。

Apiaryのアカウント設定を開き、Githubのアカウントと紐付けます。

Apiaryのドキュメントの設定を開き、Githubと連携させる設定をしておきます

Githubのリポジトリの設定を開き、Apiaryを選択します。

domainのところには、Apiaryのドメインを設定します。写真の太字の箇所が入力すべき値です。

API Blueprintはまだ発展途上で、Authorizationに対応して欲しいとかissueが上がっています。
他にもRate limitのテストなども、そもそもApi blueprintの仕様にその辺が存在しないので、別途テストを書くしかないと思います。

など細かな問題が色々残っていますが、効率よく質良くAPIサーバとAPIドキュメントをメンテナンスしていくいい方法だと思いました。

RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに－ Publickey

最後に。↑の記事の通り、先月くらいにOpen API Initiativeという団体が結成したようです。
名だたる企業たちがコアメンバーに入っているので、活動を追って行きたいと思います。