SwaggerでAPIドキュメントの生成とモックサーバーを立てる
REST APIの開発が多くなってきたので、APIのドキュメントを作成するのに良さそうなツールを探していたところ、Swaggerというものが良さそうだったので、今回はそれについて紹介していきます。
APIの開発において、フロントエンドとバックエンドを同じ人で開発する場合は、どんなAPIが存在しているのか、またそれぞれの詳細もコードを見たらすぐにわかるという状態であればドキュメントを用意しなくても問題なく開発できるかもしれませんが、開発者をフロントエンドとバックエンドで分けた場合、ドキュメントを用意しないとどういうAPIがあってどう使えばいいのかというのを把握するのが難しくなってしまいます。
APIのドキュメントを作るのには、ExcelやMarkdownで書くなど様々な方法がありますが、Excelのファイルはバイナリファイルなので、gitなどで変更の履歴を追っていくのが大変だったり、Markdownだとフォーマットの統一が難しかったりしますが、SwaggerではYAMLやJSONで記述します。
Swaggerとは
Swaggerとは、APIを定義するための仕様とそれらに関するツール群のことを指します。
Swaggerは、REST APIの仕様の記述の標準化を目指すOpen API Initiativeという団体（マイクロソフトやGoogle、IBMなどから結成）によって推進されています。
Swaggerのフォーマットに基づいた記法で作成したファイルでAPIの仕様などを記載し、それを元により見やすい形のドキュメントを生成したり、それに基づいたモックサーバーを立ち上げるといったことができます。
すぐに仕様を決めてモックサーバーを立ち上げられることによって、バックエンド側の実装を終えるまでフロントエンドの実装が行えないという状態にならず、仕様を決めてから、バックエンドもフロントエンドも同時に開発を行うことができるようになります。
Swagger関連のツール
Swaggerに関するツールには以下のように色々なものがあります。
| ツール | 詳細 |
|---|---|
| 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を使ってみる
今回は、Swagger EditorでYAMLファイルを記述し、それを元にモックサーバーを立てるといった手順を行います。
Swagger Editor
それでは、YAMLファイルの作成を行います。
YAMLファイルなので、普段利用しているエディタでももちろん書くことができますが、リアルタイムでSwaggerの構文をチェックするにはプラグインの導入が必要になったりするので、今回はSwagger Editorのオンラインエディタを利用します。
Swagger Editorでは以下のように、左がファイルの内容、右側がファイルに基づいて作成されたドキュメントが表示されます。
アクセスすると初期の状態から、ペットストアを元にしたアプリケーションのAPIドキュメントが表示されているかと思います。
今回はこれを元に、本棚アプリケーションのファイルを作成しました。
swagger.yaml
Swagger Editorで編集するとリアルタイムで変更に対応してドキュメントが変更されます。
完全にファイルをゼロから作成するのはかなり大変になりますが、このようにすでに作られているファイルから変更するのは意外とわかりやすいので、基本的な記述だけであればそれほど難しくはないかと思います。
このようにYAMLファイルやJSONファイルによって定義していくことによって、人間にもコンピューターにも読みやすい形にして、このファイルの履歴変更も見やすいのと、このファイルを元により扱いやすいドキュメントを生成することができます。
Swagger Codegen
次に、Swagger Codegenというコマンドラインツールを用いてモックサーバーを立てます。
Swagger Codegenのセットアップには様々な方法がありますが、今回はHomebrewを用いて行います。
セットアップ
$ brew install swagger-codegen
$ which swagger-codegen
/usr/local/bin/swagger-codegen
Swagger Codegenの使い方は以下のようになります。
swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l ruby -o /tmp/test/
-i 元にするjson
-l 言語
-o 出力先のフォルダ
利用できる言語は以下のようにかなり沢山あります。
$ swagger-codegen
Available languages: [ada, ada-server, akka-scala, android, apache2, apex, aspnetcore, bash, csharp, clojure, cwiki, cpprest, csharp-dotnet2, dart, elixir, elm, eiffel, erlang-client, erlang-server, finch, flash, python-flask, go, go-server, groovy, haskell-http-client, haskell, jmeter, jaxrs-cxf-client, jaxrs-cxf, java, inflector, jaxrs-cxf-cdi, jaxrs-spec, jaxrs, msf4j, java-pkmst, java-play-framework, jaxrs-resteasy-eap, jaxrs-resteasy, javascript, javascript-closure-angular, java-vertx, kotlin, lua, lumen, nancyfx, nodejs-server, objc, perl, php, powershell, pistache-server, python, qt5cpp, r, rails5, restbed, ruby, rust, rust-server, scala, scala-lagom-server, scalatra, scalaz, php-silex, sinatra, slim, spring, dynamic-html, html2, html, swagger, swagger-yaml, swift4, swift3, swift, php-symfony, tizen, typescript-aurelia, typescript-angular, typescript-angularjs, typescript-fetch, typescript-jquery, typescript-node, undertow, ze-ph]
モックサーバーの立ち上げ
先ほど作成したファイルをダウンロードなどをして、任意のディレクトリに置いてそのディレクトリ下で以下のコマンドを実行します。
今回はnodejsを用いてモックサーバーを立ち上げます。
swagger-codegen generate -i swagger.yaml -l node-server -o ./bookshelf-node
そうすると先ほどのディレクトリに、bookshelf-nodeというディレクトリが作成されるので、それを用いてサーバーを立ち上げます。
$ cd bookshelf-node/
$ npm install
$ node index.js
そうすると、localhost:8080に立ち上がります。
http://localhost:8080/docs
にアクセスすると以下のようなドキュメントが表示された画面が表示されます。
先ほどYAMLファイルで定義したパスのURLにアクセスして見ると、定義した形でJSONが返って来ます。
http://localhost:8080/v1/book/1
response
{
"name": "doggie",
"id": 0,
"status": "available"
}
http://localhost:8080/v1/user/1
response
{
"firstName": "firstName",
"lastName": "lastName",
"password": "password",
"userStatus": 6,
"phone": "phone",
"id": 0,
"email": "email",
"username": "username"
}
このように先ほど定義した型に沿って値が返ってくるため、フロントサイドはこのモックサーバーを利用して開発を行うことができます。
まとめ
Swaggerは周辺ツールがかなりあって、実際に導入する際にどのようなツールを使うのがいいかを調べて選択したり、それぞれのツールをインストールして使っていくのは大変になるかもしれませんが、Swaggerのファイルのサンプルは豊富にあり記法もそれほど難しくないのと、ドキュメントの管理が楽になることを考えるとかなりメリットが大きいと思うので、気になった方はぜひ使って見てください。
参考
