先日、Open API Initiativeの設立が発表されました（via RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに － Publickey）。これにより、RESTful APIが各企業間において標準化され、より広まっていくものと考えられます。
そんなRESTful APIを広めていく中で必要な要素になるのがドキュメントです。APIは開発者向けの画面はなく、プログラムからコールして利用します。そのため、分かりやすいドキュメントが必須になります。その標準フォーマットとして取り上げられているのが今回紹介するSwaggerです。
Swaggerとは？
Swaggerはドキュメントフォーマットおよびビューワーになります。Swagger自体オープンソースとして公開されており、関連するツールやライブラリもオープンソースとなっています。Swagger向けに書かれたドキュメントはHTMLファイルに変換できます。
項目をドリルダウンすると、HTTPメソッドとパスが一覧表示されます。これにより実装されている機能が一目で分かります。
さらに各機能をクリックすると、処理を行う際に必要なデータが分かります。
処理を行うのにOAuth2が必要な場合にはこの画面から認証へ飛ばすことができます。
そして処理を実際に行って結果を確認できます。Content Typeの指定もできますので、必要に応じてXMLまたはJSONで受け取ることも可能です。
このようにSwaggerは開発者のためのインタラクティブなドキュメントと言えます。ただ読むだけでなく、処理をその場で行って結果を確認できるようになっています。なお、SwaggerのドキュメントはJSONファイルをベースにして生成されています。つまりこのドキュメントの元になるJSONファイルさえ用意すれば、サーバサイドの言語に関係なくドキュメントが生成できるようになるのです。JSONの他、YAMLファイルも選択できます。
ドキュメントをビジュアル的に作成するSwagger Editor
ドキュメントを生成する方法は幾つかありますが、Swagger EditorはWebブラウザ上でビジュアル的に作成するツールになります。
左側にYAML、右側にそのYAMLから生成されたSwaggerドキュメントが表示されています。内容を編集すると、右側のプレビューにリアルタイムに反映されます。
このできあがった内容から、サーバサイドまたはクライアントになるライブラリを生成することができます。サーバサイドは以下のフレームワークに対応したコードになります。
クライアントライブラリも多数の言語向けに生成されます。こうしてみると、かつてのWebサービスで言うWSDLのようにも扱うことができるようです。
API SpecをもとにSDK化するSwagger Codegen
前述のSwagger Editorのメニューからクライアントライブラリを生成することができますが、API Specを用意しておき、コマンドラインでSDK化ができるOSSも公開されています。
こちらの手順に従って、環境準備して実施もよいですが、実際実施してみるとなかなかうまくいかない部分がありましたので、Dockerコンテナを使った方法を紹介します。
swagger-codegen-docker
こちらは実際に動作することを確認しています。本ツールをスクリプト化したものは、Gistにおいておきました。
swagger_sdk_build Docker環境があるかたは、実際に試してみてください。
サードパーティーからも多数のライブラリが
公式ライブラリだけでなく、例えばLaravel向けのライブラリであったり、Dropwizardもあります。探せば自分の使っているフレームワーク向けのライブラリもきっと見つかるでしょう。
これらのライブラリを使うことで、ソースコード中に書いたフォーマットに従ってSwagger向けのJSONファイルを自動生成するようになります。そうすれば開発したAPIを扱うライブラリを生成できるようになりますので、APIを利用する開発者はとても容易に開発を進められるようになるでしょう。
SwaggerはすでにAmazon API Gatewayで使われるなど、APIを公開または開発するサービスにとっては無視できない存在になっています。今後ますます利用が拡大していく中とあって、Swaggerのドキュメントフォーマットに沿って進めておくことで開発者にとって利便性が高まったり、周辺ツールを利用することで開発をよりスムーズに行うことが可能になるでしょう。
