サマリ

SwaggerはAPI開発者にとっても、APIユーザーにとっても開発が楽になるらしい。→気になった。
SwaggerではAPI仕様をOpenAPIで記述する。今自社のAPI仕様はJSON Schemaで書いている。JSON SchemaとOpenAPIは（ほぼ）互換性がある。→移行はしやすいかも。試してみよう！
というわけで試して結果、Swaggerのよかったところ、辛かったところがわかったので紹介します！

読むときの注意

※Swaggerのインストール方法や詳細な使い方などは紹介しません。

試した環境

OS: Mac OS 10.14.5
Swagger Editor v3.6.30
Docker Desktop Community ver 2.0.0.3（swaggerを試すために使用）

試した方法

Swagger Editor, Swagger UIは今回お試しということで、docker使って試しました。
docker-compose.ymlに以下の用に書いて、

swagger0editor:
  image: swaggerapi/swagger-editor:v3.6.30
  ports:
    - "50080:8080"

swagger-ui:
  image: swaggerapi/swagger-ui:v3.0.5
  ports:
    - "50081:8080"
  volumes:
    - $PWD/schema:/usr/share/nginx/html/api

以下のコマンドを実行。

$docker-compose up

http://localhost:50080/ でSwagger Editorにアクセス、
http://localhost:50081/ でSwagger UIにアクセスできます。

そもそもSwaggerって？

REST APIを開発の支援ツール。いくつかのツールで構成されている。ざっくり説明すると以下2つ。

API開発を支援するSwagger Editor
API仕様のビューアーSwagger UI

やったこととわかったこと

今回は以下のことをして、Swagger Editorの機能を試しました。
対象としたAPIは本の情報を取得するAPI openBD
※ 私が作ったものではないです。JSON Schemaで仕様が公開されていたのでと今後使いたいと思ったので対象とさせてもらいました。

OpenAPIフォーマットでAPI仕様を書いた。

今回はレスポンスについては変える必要がなさそうだったので、リクエストの仕様とAPIの説明を追記しました。

わかったこと

Editorで書くとリアルタイムにプレビューが表示されました。
また、補完機能もついていることがわかりました。ctrl+spaceで補完機能が使えます。

また、プレビューですぐに仕様に沿ったリクエストをAPIサーバーに送って実行結果を試せました。

Open APIフォーマットで書くこと自体とくに困ることはなかったです。
Swagger EditorはAPIとそのAPI仕様定義をサンプルを最初に表示してくれるのと、リアルタイムにプレビューを出してくれるので、そのサンプルをちょっと編集したら、どの項目がUIのどの項目と関連しているのかすぐわかりました。それらのおかげもあっていろいろ調べないとわからないってことはなかったです。

APIクライアントコードを自動生成して実行する

コードの自動生成も試してみました。

わかったこと

レスポンスは書いている仕様と合っているかはチェックしていない。

Swagger Editorでclient作れたから実行した。
が、エラーが発生した。

  File "/vagrant/python-client-generated/swagger_client/models/book_info_hanmoto.py", line 17, in <module>
    from swagger_client.models.big_decimal import BigDecimal  # noqa: F401,E501
ModuleNotFoundError: No module named 'swagger_client.models.big_decimal'

swagger_client.models.big_decimalというモジュールがないらしい。
swagger_client.models.big_decimalの定義をコードで探したがなかった。。

つまりtry it out機能ではAPIの実行をリクエストの定義に沿って送っているだけ。仕様とレスポンスどっちが正？ってなった。開発だったら絶対困る。
今回はHTTPレスポンスを正としてレスポンスの定義を変えて先にすすめた。

OpenAPIでの型と自動生成コードの型の変換処理が怪しい

そもそもどういう定義をしていてbig_decimalになっているのか？
調べたらnumberだった。たとえば以下のようなもの。

            dokushakakikomipagesuu:
              description: 読者書き込みページ数
              type: number
            zaiko:
              description: 在庫ステータス
              type: number

→今回はnumberで定義していたのは全部小数になることはないので、integerで定義。クライアントを再生成して実行。
→期待通りレスポンスを取得できた。

ただ、自動生成したコードはログレベルを設定して実行できるので、デバッグはしやすい。
HTTPリクエストはパラメーターとしてなにを渡しているのか？レスポンスは何が返ってきたのか？がわかるようになる。
HTTPリクエストレスポンスは期待通りだから仕様記述の問題と切り分けやすい。

まとめ

Swagger Editorを試してわかったこと。

◯仕様を書く、仕様を見せるのには使いやすいと感じた。とくに仕様見ながら1つの画面でお試し実行できるのは作る側にも見る側にとってもよい。
◯補完機能とサンプルAPIとその仕様があるので、OpenAPIフォーマットで書くのは数回やれば基本は早く習得できそう。
△自動生成されるコードはまだ信頼しきれない。けっこうな数の言語で生成できるけど、運用を考えるとサポートする言語の数はしぼりたい。

自社APIは基本JSON Schemaで書いているけど、独自な書き方もあるので、それをOpenAPIで書き換えるにはどうすればよいのか、OpenAPIの書き方をもう少し詳しく学ぶ。

その他

今回作ってみたOpen APIで書いた仕様や、実行してみたコードは参考用に以下においています。
https://gist.github.com/1021ky/5cbc576dd03daee697619c8240050d9e

また、今回試して学びとなったことは他にもあるので、それはおいおい別の記事で書いていきます。