springdoc-openapi を使うと、コードからOpenAPI定義を出せるopenapi 用のSpring profile を分けているのがうまいこの記事は、Spring Bootアプリから OpenAPI 仕様を自動生成し、それを CI pipeline に自然に組み込む方法を紹介しています。
まず前提として、OpenAPIはAPIの仕様を機械が読める形で表したものです。人間にとっては「このAPIはGETで、こういう入力を受けて、こういう出力を返す」と読めるし、ツールにとっては「クライアントコードを作るための材料」になります。
ここが大事で、OpenAPIはただのドキュメントではありません。
実際には次のような用途でかなり役に立ちます。
正直、このへんは「OpenAPIって地味だけど便利だなあ」と感じる部分です。
特に複数チームで開発していると、仕様書が生きていることの価値はかなり大きいと思います。
記事ではまず、普通のSpring Bootプロジェクトを作ります。依存関係としてはざっくりこんな構成です。
spring-boot-starterspring-boot-starter-webspring-boot-starter-securityspringdoc-openapi-starter-webmvc-uispringdoc-openapi は、Spring Bootのコードやアノテーションを見て OpenAPI 定義を生成してくれるライブラリです。
Swagger UIは、そのAPIをブラウザで眺めたり試したりする画面だと思えばOKです。
さらに application.yml で OpenAPI の出力先を設定します。この記事では、たとえば /api-docs のようなパスを使っています。
そのあと、シンプルな REST controller を作ります。内容はすごく基本的で、
GET で "Hello!" を返すPOST で受け取った文字列を JSON の Set<String> にして返すというものです。
ここまでは、OpenAPIを使うというより「普通のSpring Bootアプリ」ですね。
記事で面白いのは、Security設定をちゃんと分けているところです。
通常時は、
/api-docs/swagger-ui/*/api/v1/defaultなどにアクセスできるようにしつつ、それ以外は認証必須にしています。
そして openapi という専用の Spring profile を用意して、そのときだけは 全リクエストを permitAll にしています。
つまり、OpenAPIを自動生成するための実行時には、ドキュメント取得を邪魔する認証を外すわけです。
これ、かなり実践的です。
CIでドキュメントを取るときに認証でコケるのはありがちな事故なので、最初から「生成用の起動モード」を分けるのは賢いやり方だと思います。
アプリを起動して Swagger UI を開き、そこから /api-docs を見ることはできます。
そのレスポンスを手で保存すれば、OpenAPI仕様ファイルとして使えます。
ただし、この記事も言っているように、これは繰り返し作業になりがちで、ビルド自動化には向かないです。
ここは本当にその通りで、手動運用は最初の1回は楽でも、数回やったらだいたい面倒になります。
人間は継続的なコピペ作業に弱いので、こういうものは早めに自動化したほうがいいです。
この記事の核心はここです。
springdoc-openapi-maven-plugin は、ゼロからOpenAPIを勝手に作るわけではありません。
起動中のSpring BootアプリにあるOpenAPI endpointを叩いて、その結果を取ってくるだけです。
つまり、プラグインが動くときにアプリ本体も動いていないといけません。
なので、一般的には次の2つを一緒に使います。
spring-boot-maven-plugin
springdoc-openapi-maven-plugin
この設計は、最初は少し回りくどく見えるかもしれません。
でも、考えてみると筋が通っています。
「コードから仕様を作る」のではなく、実際に動くアプリから仕様を抜き出すので、実装との差異が出にくいんです。ここはかなり重要です。
openapi profile を切る意味記事では Maven profile openapi を追加します。
これがあることで、OpenAPIを生成するときだけ以下のような挙動に変えられます。
openapi profile で起動openapi.yml を生成するこの「専用モードを用意する」という発想が、私はかなりきれいだと思いました。
本番用のセキュリティ設定を無理に壊さず、生成用途だけ別に逃がしているからです。
CI/CDの文脈では、こういう分離があとあと効いてきます。
ビルドのためだけに本番設定をいじるのは、だいたい危ないので。
このレシピの良さは、単に「OpenAPIを出せます」ではなく、CIに乗せやすい形にしていることです。
たとえば、こんな流れが作れます。
openapi profile で起動/api-docs.yaml から取得openapi.yml をビルド成果物として保存この流れにしておけば、API仕様がコード変更に追従しやすくなります。
手で更新する仕様書より、ずっと現実的です。
個人的には、OpenAPIの価値は「きれいな仕様書」そのものより、周辺ツールとの接続点になることにあると思います。
生成、モック、契約テスト。ここにつながると一気に強いです。
もちろん、OpenAPIを自動生成すれば全部解決、ではありません。
なので、私は「自動生成 + 必要なところだけ手で磨く」のが現実的だと思います。
ゼロから全部手書きするより、かなり楽ですし、ズレも減らせます。
この記事は、Spring Bootアプリから OpenAPI を自動生成し、それを Maven ビルドと CI に組み込むための、かなり実践寄りのレシピでした。
特に重要なのは、
openapi profile で生成用のアクセス制御を分けるという3点です。
見た目は少しややこしいですが、やっていることはかなり素直です。
「動いているアプリから、動く仕様を抜く」。
この発想は、実務ではかなり強いと思います。
参考: OpenAPI From Code With Spring and Java: A Recipe for Your CI