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

この記事はWeb API Advent calendarHamee Advent Calendar 2015の6日目です。

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

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

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

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

まえおき

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

API BlueprintでAPIドキュメントを書く

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

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

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

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

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

APIサーバを実装する

Goに入門してRedis+PostgresなアプリをHerokuにデプロイするまで で作成したLeko/godemoリポジトリに書き足します

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

Apiaryに公開する

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

  • ドキュメントページ(HTML)
  • ↑のホスティング
  • 各APIを試せるplayground
  • 各APIを試せるサンプルソース
  • 実装がなくても仕様があれば動くモックサーバ

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

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

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

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

早速テストしてみます。テストには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タブに記述されています。

Scree

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

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

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

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

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

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

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

Githubと連携する

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

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

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

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

Scree

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

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

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

Scree

まとめ

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

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

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

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