この記事はWeb API Advent calendarとHamee Advent Calendar 2015の6日目です。
\nSPAやハイブリットアプリを仕事でも趣味で作っているので、APIサーバを実装する機会が増えています。
\n手軽にしっかりしたドキュメントを書けて、かつ実装とドキュメントの整合性を保つのってコスト高いな…。と悩んでいます。
Web APIのドキュメントといえば、SwaggerやJSON-Schemaあたりが有名かと思います。
\n例えばQiitaのAPIv2はJSON-Schemaを使用して書かれています。
今回はそれらとは違うAPI Blueprintというツールを使用してAPIドキュメントを作成し、そのAPIドキュメントを自動テストとして実行できるDreddというツールを使用し、
\nAPIドキュメントを書いたら、APIサーバのテストもできる 方法を残します。
ついでにAPI Blueprint形式のドキュメントをホスティングしてくれるApiaryとGithubを連携し、masterにマージされたら公開されているAPIドキュメントも最新になるというのもやってみます。
\n\n今回作成したデモは Leko/godemo にて公開しています。
\n今回作成したAPIドキュメントは こちらにて公開してます。
今回はデモとしてTODOアプリ用のAPIを作ってみます。
\nという2つの機能を持つAPIサーバのドキュメントを書きます。
\n詳しい記述方法についてはAPI Blueprintの仕様を御覧ください。
\nだいたいこんな感じになるかと思います
書いたら、プロジェクト直下にapiary.apibというファイル名で保存しておきます。
\nファイルの内容はMarkdownですが、API Blueprintというフォーマットで記述しているため拡張子はapibです。
Goに入門してRedis+PostgresなアプリをHerokuにデプロイするまで で作成したLeko/godemoリポジトリに書き足します
\n今回はGoの話ではないですし、先ほどの仕様の通りに作っただけなのでさっくり済ませます。
\nApiaryは、API Blueprintで書かれたAPIドキュメントをもとに
\nなどなどをまるっと生成してくれるサービスです。
\nオレオレドキュメントで作成・管理はかなり手間が大きいと思います。
\nplaygroundをいちいち作ったり、サンプルコードで複数言語に対応したり、見やすいドキュメントにしたり、書き手として一貫したドキュメントにすること、など実装のコストもメンテナンスのコストも高くつきます。
そんなつらみをApiaryが助けてくれます。
\n保守コストを抑えつつ、見る人にとってより使いやすい、読みやすいドキュメントを作るための手段の一つだと思います。
早速テストしてみます。テストにはApiaryが提供するdreddというツールを使用します。
\n導入の注意点として、Dredd周りのツールがNode4や5に対応しておらず、dreddを入れるためにはnode0.10系が必要になります。 古い…。
\n\nError compiling on Mac OS X 10.10.5 #287
\n
\nSupport for node v4.X #292
npm i -g dreddテストの環境のセットアップは、ApiaryのTestsタブに記述されています。
\nGoのサーバを起動しておき、書かれているとおりにコマンドを実行します。
\ndredd init # 省略,対話CLIがあります\ndredd↑こんな感じになります。
\nさらに、 Apiaryの言うとおりにdredd initしておくと、そのテストの通知結果が集約される ようになっています。
立てておいたGoのサーバに対してHTTPリクエストが飛び、どんなレスポンスが返ってきたかをテストしてくれます。
\nこれで実装が変わっても、ドキュメントが変わってもコマンド一つで整合性を確認できます。
リクエストと対応するレスポンスのパターンを書けば書くほどテストケースが増えるので、
\nドキュメントをしっかり書くことがテストのクオリティ向上、ひいてはプロダクトの質向上に繋がる ところが、ドキュメントを書くモチベに繋がるなと感じます。
反映漏れや食い違いを起こさないために、
\nAPIドキュメントをGitで管理して、GithubのmasterにpushされたらApiaryのドキュメントに自動反映されるようにします。
Apiaryのアカウント設定を開き、Githubのアカウントと紐付けます。
\nApiaryのドキュメントの設定を開き、Githubと連携させる設定をしておきます
\nGithubのリポジトリの設定を開き、Apiaryを選択します。
\ndomainのところには、Apiaryのドメインを設定します。写真の太字の箇所が入力すべき値です。
\nAPI Blueprintはまだ発展途上で、Authorizationに対応して欲しいとかissueが上がっています。
\n他にもRate limitのテストなども、そもそもApi blueprintの仕様にその辺が存在しないので、別途テストを書くしかないと思います。
など細かな問題が色々残っていますが、効率よく質良くAPIサーバとAPIドキュメントをメンテナンスしていくいい方法だと思いました。
\n\n\nRESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに － Publickey
\n
最後に。↑の記事の通り、先月くらいにOpen API Initiativeという団体が結成したようです。
\n名だたる企業たちがコアメンバーに入っているので、活動を追って行きたいと思います。