Swaggerとは何か？ - プログラマでありたい

f:id:dkfj:20151202082224p:plain

　最近、Swaggerという単語を聞く機会が増えていませんか？MicrosoftやGoogle,IBMが、REST APIの記述標準化を目指した「Open API Initiative」という団体を立ち上げ、そのベースをSwaggerを利用するということで一躍注目を集めるようになりました。しかし、Swaggerというものを調べるとツールの話やドキュメントの話が出てきて、何なのこれとなることが必定です。ということで、WebAPIとは切っても切れない関係のSwaggerの話を簡単にしてみます。

Swaggerとは？

　Swaggerとは、一義的にはREST APIを記述する為の仕様です。当初から、Swaggerが標準の仕様になることを目指しますよと宣言していて、米国等ではデファクト・スタンダードとなっていました。それが、「Open API Initiative」が出来たことにより、実際に標準の仕様になる可能性がかなり高くなったというのが現状です。しかし、この説明をしてもピンとこないのは、SwaggerにはSwagger EditorやSwagger UIなど数多くのツールがあることです。標準化仕様とツールの関係性はなんなのでしょう？
　特に調べた訳ではないのですが、Swaggerの仕様を普及を後押しする為に作っていった便利ツールでしょう。利用者視点で考えれば、これらのツールこそがSwaggerです。

Swaggerの用語説明

Tool	Description
Swagger Spec	REST APIに対して Swaggerの仕様に準じたドキュメント
Swagger Core	REST APIの実装からSwagger specを生成するためのライブラリ
Swagger Codegen	コマンドラインツール Swagger JSONからクライアントコード生成
Swagger UI	SWagger 準拠 API （Swagger SPec）から動的にドキュメントを生成するツール
Swagger Editor	ブラウザ上で動くJSON/YAMLのエディタリアルタイムで構文チェック

サードパーティも含めるともっと沢山ありますが、まずはこれくらい覚えておいたら充分でしょう。そして、まず最初に使うのはSwagger UIとEditorでしょう。

Swaggerを使うと何が嬉しいの？

　ところで何故Swaggerがデファクト・スタンダードと呼ばれるほど普及しているのでしょうか？色々な要因ありますが、Swagger UIとSwagger Editorが秀逸なためではないでしょうか？Swagger UIはSwaggerの書式（Swagger Spec）で書いておく自動的にドキュメント化してくれます。いわゆるコードからドキュメント生成というやつですね。それだけではなく、そのドキュメントから実際のリクエストが投げられます。仕様書からテストまで出来るという優れものです。投げるパラメータは随時変更できるので、ツールとして便利ですね。幾つか使用例ありますが、SORACOMさんのAPIドキュメントもSwagger使っています。是非、下記のリンクからAPI リファレンスを見てください。Swaggerの有用性の一端がすぐに解ります。

API リファレンス | SORACOM Developers

　次にSwagger Editorです。JSONにしろ、YAMLにしろ人間の手で書くには辛すぎる代物です。そこを手助けしてくれるのが、Swagger Editorです。構文チェックや、リアルタイムでのドキュメント化など、少しだけ手助けをしてくれます。また、記述した定義を元に、サーバサイドのコードを出力するような機能もあります。いわゆるIDEに近いものがあります。

f:id:dkfj:20151202063228p:plain

まとめ資料

Swaggerで始めるモデルファーストなAPI開発 from Takuro Sasaki

www.slideshare.net

標準化団体の出現でSwaggerはどうなるか？

　ところで標準化団体の出現でSwaggerはどうなるのでしょうか？標準化はSOAPやWDSLが来た道で必ず失敗するという人もいますが、ちょっと違うような気がします。Swaggerは、SOAPのようにプロトコルではありません。ただのRESTの記述方法の定義です。ということでレイヤーが違うかなと思います。またSwaggerは標準化団体ありきで利用促進されている訳ではありません。デファクト・スタンダードの地位を取った後に、その標準化を支援する団体が出来たという流れです。ということで、元々使っている人たちは、標準化しようがしまいが利用し続けると思います。そう言った点は強いのではないでしょうか。（とは言っても、それほど寿命が長いものとは思えませんが。。。）
　ちなみに標準化団体が出来たことにより、今後は変化は小さく歩みは遅くなると思います。使いづらいところの改善は望みにくくなりますが、バージョンごとの苦労は少なくなると思うので仕方がないでしょう。

Amazon API Gatewayとの関係

　いろいろとSwaggerのことを書き散らかしたのですが、個人的には標準化団体の動きには全く興味がありません。気になるのはAmazon API Gatewayとの関係性のみです。API Gatewayは、2015年7月に鳴物入りで登場したサービスです。サーバレスアーキテクチャなどの重要なキーとなるサービスの1つで、おそらく今後使い倒していくことになります。しかし、使ってみたところUIベースで使っていくのはかなり厳しいです。運用を考えると、Swaggerで設定をインポートするという使い方が現実的です。ということで、使わざるを得ないというのが正直なところです。皆さん、諦めて使いましょう。
　Swaggerは、ツールの方向性とかはセンスが良いと思うのですが、配布方法とかは絶望的にダメです。その辺り何とかしないのかなぁ。有志が勝手になんとかしろということなのでしょうか。