Spring Boot のエンドポイントが OpenAPI Spec を満たしているかを検証する

雑記。OpenAPI Spec の使い方について。

最近 REST API とその利用コンポーネント(例えば UI)の開発を独立に進めるべく、OpenAPI Spec を使っている。

  • まず API の仕様を考えて OpenAPI Spec で定義する
  • 利用コンポーネントは Spec を元に openapi-generator で stub サーバを生成して開発を進める
  • API は定義した Spec を満たすように実装を進める

これによって API 側と UI 側で仕様の齟齬の無い開発を進めることはできているが、UI の方が開発が進んでいる時に、どのエンドポイントまでが API実装済みかを確認したいことがあった。

実際に開発環境でデプロイされている API のエンドポイント一覧がわかれば、OpenAPI Spec の YAML と照らし合わせることで実装状況を可視化することができそう。今回 API は Spring Boot で実装していたので、Spring Boot Actuator を入れて /actuator/mappings でエンドポイント一覧の情報を JSON で取れるようにした。

ひとまず API の実装がどこまで進んでいるのかが一目ですぐわかるようになったので、この手法をブレークダウンしてより細かい可視化や確認を進めてもいいが、

  • リクエスト/レスポンス形式の確認は、そもそも Generation Gap パターンなどで乖離が起きないようにした方がいい
  • 動いているかの確認なら Spec からテストを生成したほうがいい(まだ調べていないが既存手法が何かしらありそう)

と思っているので、そちらのアプローチも検討したいところ。