Springdoc-openapiとは？Spring Boot 3/4での導入方法とバージョン選定を解説【2026年最新】

Springdoc-openapiは、Spring BootのREST APIからOpenAPI仕様書とSwagger UIを自動生成するJavaライブラリです。コントローラーのコードを解析してAPIドキュメントを常に最新に保てるため、手書きの仕様書のようにコードと乖離しません。ただし2024年以前の情報には注意が必要で、依存関係の名前とバージョンはSpring Bootの世代（2系／3系／4系）によって変わります。この記事は導入方法・バージョンの選び方・つまずきどころを、2026年時点の正しい構成でまとめます。

まとめ：Springdoc-openapiの要点

• 役割：Springのコントローラーから/v3/api-docs（OpenAPIのJSON）とSwagger UI画面を自動生成する。開発が停滞したSpringFoxの実質的な後継。
• 依存関係（重要）：Spring Boot 3系以降はspringdoc-openapi-starter-webmvc-uiを使う。旧来のspringdoc-openapi-uiはSpring Boot 2系向けの旧v1で、3系以降では動かない。
• バージョン：Spring Boot 2系→v1系、Spring Boot 3系→v2系、Spring Boot 4系→v3系。世代を合わせないと起動時エラーやSwagger UIの404になる。
• アクセス先：導入後は/swagger-ui.htmlでUI、/v3/api-docsでJSON定義を確認できる。

Springdoc-openapiが提供するもの

Springdoc-openapiは、実行中のアプリのルーティングやリクエスト／レスポンスの型を読み取り、OpenAPI 3形式のAPI定義を生成します。生成物は主に2つです。ひとつはマシン可読な定義ファイル（/v3/api-docsで配信されるJSON、YAMLも取得可）、もうひとつは人が操作できるSwagger UIの画面です。Swagger UIからはブラウザ上で各エンドポイントにリクエストを送って動作を試せるため、フロントエンド担当や外部連携先に仕様を渡す用途で使われます。

コードから定義を起こすので、エンドポイントを追加・変更すればドキュメントも自動で追従します。@Operationや@Schemaといったアノテーションで説明文や例を補えますが、アノテーションが無くても基本的な定義は生成されます。

Swagger・OpenAPI・SpringFoxとの関係

用語が混同されがちなので整理します。OpenAPIはAPI仕様の記述フォーマット（規格）そのもの、Swaggerはその規格を扱うツール群（UIやエディタ）の名前です。Springdoc-openapiは「OpenAPI形式の定義を生成し、その閲覧用にSwagger UIを同梱する」ライブラリという位置づけになります。規格と実装の違いはOpenAPIとは｜Swaggerとの違い・仕様書の書き方で詳しく整理しています。

かつて同種のライブラリとしてSpringFoxが広く使われましたが、Spring Boot 3系への対応が進まず更新が停滞したため、現在の新規プロジェクトではSpringdoc-openapiが標準的な選択肢になっています。SpringFoxから移行する場合はアノテーションや依存関係の置き換えが必要です。

バージョンと対応するSpring Boot（選定の要）

Springdoc-openapiでもっともつまずくのがバージョン選定です。使っているSpring Bootの世代に合わせてSpringdoc-openapiのメジャー系列を選ぶのが原則で、ここを外すと依存関係の解決や起動に失敗します。

v1とv2以降で最大の違いは依存関係の名前が変わった点です。v2以降はモジュールがすべてspringdoc-openapi-starter-接頭辞に改称され、Spring Boot 2系向けのspringdoc-openapi-uiという名前は使いません。またv2.8.0以降は生成される定義の既定バージョンがOpenAPI 3.1になっています。Spring Boot自体の世代やサポート期限の判断はSpring Bootバージョン一覧とサポート期限、Spring Boot 4での変更点はSpring Boot 4の変更点を参照してください。

個別のパッチ番号（例：2.8系・3.0系の末尾）は更新が速いため、実際の最新版は公式サイト（springdoc.org）やMaven Centralで確認してから固定するのが安全です。

依存関係の追加（Maven / Gradle）

もっとも多いSpring Boot 3系（v2系を使用）の例を示します。Webアプリ（Spring MVC）ではこの1つを追加すれば、OpenAPI定義の生成とSwagger UIの両方が有効になります。

Mavenの場合はpom.xmlに次を追記します。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.17</version>
</dependency>

Gradleの場合はbuild.gradleに次を追記します。

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.17'

リアクティブなSpring WebFluxで構築している場合は、末尾を-webmvc-uiではなくspringdoc-openapi-starter-webflux-uiに置き換えます。Spring Boot 4系ではartifactIdは同じで、バージョンをv3系（3.0系）にします。Spring Boot 2系の旧プロジェクトのみ、旧名のspringdoc-openapi-ui（v1系）を使う点に注意してください。

Swagger UI・api-docsへのアクセスと設定

依存関係を追加してアプリを起動すると、追加設定なしで次のURLが有効になります。

• Swagger UI（画面）：http://localhost:8080/swagger-ui.html
• OpenAPI定義（JSON）：http://localhost:8080/v3/api-docs（末尾を.yamlにするとYAML）

パスや表示はapplication.properties（またはYAML）のspringdoc.*で変更できます。よく使うのは公開パスの変更と、環境ごとの有効・無効の切り替えです。

springdoc.swagger-ui.path=/swagger-custom.html
springdoc.api-docs.path=/v3/api-docs
springdoc.api-docs.enabled=false

上記のようにenabledをfalseにすると、その環境ではドキュメント生成ごと無効化できます。本番でSwagger UIを見せたくない場合の基本的な手段です。

導入でつまずきやすい箇所と対処

Spring Boot 3にしたらSwagger UIが404になる

もっとも多い原因が旧v1の依存関係（springdoc-openapi-ui）を残したままSpring Boot 3系へ上げたケースです。v1はjavax名前空間・Spring Boot 2系前提のため、jakartaへ移行した3系では正しく動かず、UIが表示されません。依存関係をspringdoc-openapi-starter-webmvc-ui（v2系）へ置き換えれば解決します。SpringFoxからの移行でも同じ置き換えが必要です。

本番環境にSwagger UIが公開されてしまう

Swagger UIは全エンドポイントの構造を露出するため、認証の外に置くと情報漏えいにつながります。本番では前述のenabled=falseで無効化するか、Spring Securityで/swagger-ui/**と/v3/api-docs/**を保護してください。アクセス制御の実装はSecurityFilterChainの解説が参考になります。開発環境だけ有効にする運用が無難です。

特定のエンドポイントだけドキュメントに出ない

Springdoc-openapiは公開されているコントローラーのマッピングを走査するため、コンポーネントスキャンの対象外やパスのグルーピング設定によって拾われないことがあります。springdoc.paths-to-matchやpackages-to-scanで対象範囲を明示すると安定します。

よくある質問

Springdoc-openapiは無料で使えますか？

Apache License 2.0のオープンソースで、商用利用を含め無料です。ライセンス表記を守れば受託開発のプロダクトにも組み込めます。

SpringFoxとどちらを使うべきですか？

新規開発ではSpringdoc-openapiを選びます。SpringFoxはSpring Boot 3系への対応が実質的に止まっており、現行のSpring Bootでは動作しないためです。

springdoc-openapi-uiとspringdoc-openapi-starter-webmvc-uiの違いは？

前者はSpring Boot 2系向けの旧v1、後者はSpring Boot 3系以降向けのv2/v3です。名前だけ似ていますが対応世代が異なるため、Spring Boot 3系以降では必ず後者を使います。

Spring Boot 4でも使えますか？

使えます。Spring Boot 4系にはSpringdoc-openapi v3系（3.0系、Java 21以上）が対応します。artifactIdはv2系と同じspringdoc-openapi-starter-webmvc-uiで、バージョンをv3系にします。

アノテーションを付けないと動きませんか？

アノテーション無しでも、コントローラーの構造から基本的なOpenAPI定義は生成されます。@Operationや@Schemaは説明文・例・必須項目などを補足したいときに追加します。

関連記事

• OpenAPIとは｜Swaggerとの違い・仕様書(YAML/JSON)の書き方とSwagger UIをわかりやすく解説
• Spring Boot 4とは？最新バージョン4.1の変更点・新機能とSpring Boot 3との違いを解説【2026年最新】
• Spring Bootバージョン一覧とサポート期限【2026年7月】最新4.1と3.5 EOL後の選び方
• Spring WebFluxとは？ノンブロッキング・リアクティブなWeb開発の基礎【2026年版】
• SecurityFilterChainとは何かを初心者にもわかりやすく解説