Play プロジェクトに Swagger UI を導入した話

はじめましての方ははじめまして。Scala エンジニアの Javakky です。

なぜ Swagger を導入するのか？

弊チームの提供している API のドキュメントはこれまで Notion で管理していました。Notionはチームのナレッジ共有として大変便利なのですが、この用途ではデプロイ後に手動で書き換えが必要だったり、変更履歴が見づらかったりといった問題点がありました。

また、各環境でエラー対応を行う場合には、 curl を利用した呼び出しをおこなっていました。

社内の他チームで採用実績のあった Swagger UI が上記を快適にしてくれそう。というモチベーションから、導入検討が始まりました。

Swagger API spec generator for Play

弊チームでは Scala + sbt + Play Framework を利用した開発がベースのため、 routes ファイルから swagger.json を生成してくれる https://github.com/iheartradio/play-swaggerを導入しました。 github.com iHeartMedia 社という企業ベースの OSS であること、ルーティングファイルのみの変更で利用ができることなどが決め手となり採用しました。

導入手法

https://github.com/iheartradio/play-swagger リポジトリに記載されている例の通り、 routes ファイルにコメントとして swagger.json に記載したい追加情報を記載することで、立ち上げ時に target/public/main/swagger.json が生成されます。

### 
# summary: create a card
# tags:
#   Card Endpoints
# responses:
#   200:
#     description: success
#     schema:
#       $ref: '#/definitions/com.iheart.api.Protocol.CardCreated'
### 
POST      /users/:profileId/contexts/:contextName/cards       controllers.api.Cards.createCard(profileId: Int, contextName: Option[String])

その他選択肢

github.com - OpenAPI から Play 用のコードを生成してくれるライブラリ - 既にある大量のコードの置き換え労力が大きく断念した

github.com - Play のコードにアノテーションを付与することで swagger.json を生成してくれるライブラリ - コードファイルにドキュメンテーションを行うことで、ファイルサイズが肥大し普段の開発効率が低下する懸念から不採用となった

Swagger UI のページを公開する

過去記事で言及した管理画面の 1ページとして Swagger UI のページを公開しました。 inside.pixiv.blog 理由としては、管理画面の権限管理機能が利用できること、 API 呼び出しには Basic 認証が必要なことなどからセキュリティ的なリスクは少ないと判断したことが挙げられます。

OSS への貢献

https://github.com/iheartradio/play-swaggerでは value: Option[String] ?= None という風にデフォルト値として None を指定した場合にはエラーになってしまう問題があったため、 PR を出すことで解決しました。

PUT /defaultValueParamOptionalString com.iheart.controllers.DefaultValueParam.put(optionFlag:Option[String] ?= None)

github.com

また、現在リリース待ちではありますが、 /conf に設置した JSON または YAML ファイルを swagger.json に含めることができる機能も開発しました！ github.com

おわりに

Swagger UI の導入により、弊チーム内でもドキュメントの Git 管理と API 呼び出しの簡易化が行えるようになりました！

チームの API には大量にドキュメントがあるため今すぐ運用とはいきませんが、地道な移行を経て完全に置き換えられることを楽しみにしています。 swagger.io また、私的な話にはなりますが、https://github.com/iheartradio/play-swaggerのメンテナとしても活動していくことになりましたので、ツールについてのご意見ご感想があればぜひぜひ issue を立ててお知らせください！