APIドキュメントを支える技術 2016
1年くらい前に、APIドキュメントについて書いたけれど、最近また少し便利なことが増えてきている。
Swagger 2.0, API Blueprint が進歩してきている
Swagger – The World's Most Popular Framework for APIs. もライブラリが増えたり、エディタが進化したり、clientの生成が楽になったりと、ちょっと前に比べて使いやすくなってきている。
API Blueprintも Schema セクションを記述すればバリデーションにも使える。それにDockerもだいぶ浸透して、ドキュメント生成ライブラリのaglioのDocker imageも簡単に用意できる ので、生成の手間がものすごい減っている。
Validationは、ドキュメントにJSON Schemaを定義する
APIドキュメントに話を戻すと、ドキュメントの内容を使ってValidationをするときは、Swagger も API Blueprint も JSON Schemaを記載しておいて、テスト実行時にそれを使って検証をする。Swagger 2.0は、responseに記載が可能だし、Blueprint も上で書いたとおり、Schemaの記載ができる。
コードからドキュメントやクライアントを生成する
最近はコードから各種のクライアントライブラリを生成して運用するのでも問題ない状況になってきている。 https://github.com/goadesign/goa は、DSLめいた仕様を記載すれば、Goのモデル部分やswagger、jsのクライアントを生成してくれたりする。
それに grpc / grpc.io も浸透してきている。 これを導入できれば、Protocol Buffersを定義して、クライアントを生成して、それを呼び出し元に渡すという作業フローができる。API仕様書を各担当に渡して人の目で見て実装するという作業がだいぶ減る。
AWSのAPI GatewayもSwaggerサポート*1しているし、ドキュメントを書けばある程度サーバーの構築が完了し、後は裏のデータのやり取りなどの調整をするくらいになった。 どんどんサーバーアプリケーションサイドは楽になっていく。データの設計もクライアント側が考慮するようにすれば、サーバーアプリケーションサイドはほとんど必要もなくなるかもしれない。
