GoConの前哨戦として各種API仕様記述フォーマットについて概要を述べておく

この記事はGoCon 2016 springで話す内容を圧縮するためのものです。
WebサービスのAPI仕様を記述したりするためのそれなりに有名な仕様について、筆者(@vvakame)の私見を述べていく。

なお、Google Trendの結果を見ると…。

仕様を調べてSwaggerを選択する事にしたのは1年弱程度前のはずなので、もし "今はそれもうできるよ！" とかあったらコメントなどで教えてください。

RAML

RESTful API Modeling Language なので、手書きを前提にしている。
YAMLで頑張って仕様を書く。

Spec

APIs Explorerっぽいものもあるっぽい。

総評

比較的広く使われているようでパワを感じる。
まず仕様が先というスタイルなのがめんどくさそう。
YAMLなのがちょっとイヤ。

RAMLからGoとJavaScript(TypeScript)向けコードを生成するライブラリがあまり見当たらない。

apiary.io

apiaryは仕様ではなくサービス。
先にドキュメントを書き、実装が追いかけるスタイル。
Mock APIサーバが自動生成される！最高！
使いやすいAPIs Explorer相当のものがある。
cliがあったりGitHubのリポジトリにドキュメントをsyncしてくれたりもする。

実際にはAPI Blueprintという仕様を使う。
Specを見るとなかなか辛い。
Modelに名前をつけて使いまわしたり、仕様の記述を複数ファイルに分割する事ができず、時間が経つにつれメンテが困難になっていく。
JS書く人とサーバAPI書く人が別々で、JS書く人が最初に動き出してうまくAPI仕様も設計できるのなら選択してもよいかも。

総評

Topgate社ではJS書く人はだいたいサーバAPIも書けるので先にサーバAPIから作ればモックとか不要なので微妙。
ドキュメント代わりにメンテし続けるには記述性・モジュール性などがちょっと辛すぎる。
apiaryの作り自体は非常に良いが、API Blueprintからのクライアントライブラリの生成などの周辺ツールにデファクトが見当たらないのもマイナス。

JSON Schema

API BlueprintのMSONやCloudEndpointsのモデル記述部、Swaggerのモデル記述部など、JSONの仕様記述にはだいたいコレが使われている。
名前通り、JSONの仕様を記述するのには十分な能力を持っている。
しかし、APIの仕様を記述するための仕様ではないのでそこは注意。

総評

ツールもふんだんにあり、色々な仕様のHUB的存在でありありがてぇありがてぇ…！
ただし、APIの仕様を記述するフォーマットとして直接使う事はなさそう。

Swagger

http://swagger.io/
https://openapis.org/

仕様全体はJSONで書く。
主にコードから仕様を生成する用途で作られている気がする。
Javaでは広く選択されている印象があり、Web上の情報もJava向けのものが多いように思う。
APIs Explorerっぽいものもある。

OAI(Open API Initiative)が仕様をシメる事になったらしい。
Google, Microsoft etcがパートナーらしいので長い物フェチの人におすすめ。
OAIの仕様はスタート時点では完全にswaggerのコピーなのでこれから更に普及することが期待される。

総評

将来性ありそう。
元Java屋さんなので見る目が優しくなっちゃう。
swagger-uiの出来はAPIs Explorerと比べると今ひとつ…。

CloudEndpoints

https://developers.google.com/discovery/
https://cloud.google.com/endpoints/

Google謹製。
コードからJSONを生成するタイプの奴。
GoogleもCloudEndpoints互換の仕様を数多くのAPIで出力している。

APIs Explorerの出来が大変良い。
あまりの良さに一回使うとAPIs Explorerが無い開発フローを想像するとちょっと体調が悪くなる。

しかし、appengine信者ですら辛い仕様の数々が心を折ってくる。

• appengine縛り
• Googleがハンドルする闇システムが間に挟まり、しかも挙動が怪しい
• カスタムドメイン不可
• ユーザ認証がGoogle認証縛り

実際に1年程度CloudEndpointsを使ってサービス開発してました。
その他、サーバ用ライブラリの仕様が辛かったりなど不満は尽きぬ。

しかし、JSONから各種クライアントライブラリの生成やUIなどはGoogle自身が同等の仕様を使い込んでるだけあって豊富。

総評

もうちょっと自由度があって安定性があって開かれた仕様だったら最高だった…。

gRPC

Google謹製2。
HTTP2前提のAPI仕様記述+ProtocolBuffers的なやつ。
Googleも今後ガリガリ使ってくるだろうし、ある程度良さそう。

しかし、ブラウザ上で動くJavaScriptがHTTP2をお話できないので現時点では多くの開発で選択肢から外れてしまうと言わざるをえない。
たぶんGoogle先生は内部でgRPC用のAPIs Explorer的なもの作ってると思うんですよね。
オラッぴょんぴょんしてみろよ！！

総評

18ヶ月後くらいにもう一回考える。

結論

自社ないし自分が関与するグループのスキルセットや開発スタイルによって最適な答えは変わる。
開発元の考えたレールから外れるとつらい目にあうのは世の常であろう。素直な使い方が自分に合致しているものを選ぼう。

サーバ側APIが先行して開発 + 実装からドキュメントを生成するスタイルの開発であれば僕の意見は参考になるはず。

• サーバ側APIが先行して開発に入る
• 実装からJSONなどを生成する。仕様を手書きして実装をそれにあわせるのは嫌
• 優れたAPIs Explorer相当の何かが必要
  • パラメータの入力がし易い
  • 他人とURLを使ってAPIの使い方が共有できる
• TypeScript用の型定義ファイルが生成できる
• Go向けのクライアントライブラリが生成できる

これを全部満たすのがCloudEndpointsだったんですよね…

とりま将来性考えるとSwaggerでいいんじゃないですかね。
Swagger以外だとRAMLになりそう。
apiaryを使って1年以上開発を続けていて今なお有効に使えている人がいたらぜひ紹介記事とか書いてほしいです。