Springdoc-openapiとは？Spring Boot 4・3での導入方法とバージョン対応表【v3.1.1】

Springdoc-openapiは、Spring BootのコントローラーからOpenAPI定義（JSON・YAML）とSwagger UIの画面を自動生成するJavaライブラリです。依存関係を1つ足せば動きますが、Spring Bootの世代とSpringdocの系列が合っていないと、起動に失敗するか、起動してもSwagger UIとAPI定義のURLが404になります。この記事では2026年10月19日時点の最新版（Spring Boot 4向け3.1.1、Spring Boot 3向け2.9.1）を前提に、選び方・設定・つまずき方を、Spring Boot 4.1.1と3.5.16で実際に動かした結果とあわせて示します。

まとめ：Springdoc-openapiの導入で押さえること

• Spring Boot 4なら3.1.1、Spring Boot 3なら2.9.1。artifactIdはどちらもspringdoc-openapi-starter-webmvc-ui（WebFluxは-webflux-ui）。Javaは両系列とも17以上で動く。
• 旧名のspringdoc-openapi-ui（1.8.0で更新終了）はSpring Boot 2向け。Spring Boot 4に入れると起動はしても/swagger-ui.htmlも/v3/api-docsも404になる。
• 画面は/swagger-ui.html（/swagger-ui/index.htmlへ302）、定義は/v3/api-docs。既定の出力はOpenAPI 3.1.0。
• 本番で止めるならspringdoc.api-docs.enabled=false。springdoc.swagger-ui.enabled=falseだけでは画面が消えるだけで、JSON定義は200で返り続ける。
• 3.x系（3.0.3以降）にはREST APIをAIエージェント用のMCPツールとして公開する機能がある。3.1.1から明示的に有効化しない限り何も登録されず、有効化した/mcpには認証が無いので、Spring Securityで守る前提で使う。

Springdoc-openapiの役割

実行中のアプリから生成される2つの成果物

Springdocは起動したアプリのリクエストマッピング、引数と戻り値の型、Bean Validationの制約、io.swagger.v3.oas.annotationsのアノテーションを読み取り、OpenAPI形式の定義を組み立てます。成果物は、機械が読む定義（/v3/api-docsのJSONと/v3/api-docs.yamlのYAML）と、人がブラウザで操作するSwagger UIの2つです。パス・HTTPメソッド・引数と戻り値の型はコードから自動で反映されるため、エンドポイントを変えれば定義も追従します。アノテーションを1つも付けなくてもここまでは出力されます。一方、エラー応答の種類や説明文はアノテーションで書いた内容がそのまま出るので、後述のように書き方を誤ると実装と食い違います。

OpenAPI・Swagger・SpringFoxとの関係

OpenAPIはAPI定義の書式（仕様）、SwaggerはそのUIやエディタなどツール群の名前で、Springdocは「OpenAPI定義を生成し、閲覧用にSwagger UIを同梱する」立場です。仕様の版ごとの違いはOpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方で整理しています。同じ役割のSpringFoxは、GitHubの最新リリースが2020年7月14日の3.0.0のままで、jakarta名前空間のSpring Boot 3以降に対応していません。いま新しく選ぶ理由は無く、移行手順は後半の章にまとめました。なお公式サイトが「not maintained by the Spring Framework Contributors」と明記しているとおり、SpringdocはSpring公式の製品ではなく、コミュニティ主導のプロジェクトです。

Spring Bootの世代別バージョン対応表

Springdocのメジャー版はSpring Bootのメジャー版と歩調を合わせて上がります（GitHubのREADMEの「Versioning」に明記）。版の選択はSpring Bootの世代で決まり、迷う余地はほぼありません。最新版はMaven CentralのメタデータとGitHubのリリース一覧で2026年10月19日に確認した値です。

3.x系がJava 21必須という説明を見かけますが、誤りです。3.1.1のjarに含まれるクラスファイルのバージョンは61（Java 17）で、公式サイトも「Spring-boot v4 (Java 17 & Jakarta EE 9)」と書いています。Spring Boot 4自体もJava 17から動きます。

公式サイトのFAQにある互換表は、3.x系について「4.0.x→3.0.x」の1行しか載っていません。ただし3.1.0のリリースノートがSpring Boot 4.1.0への追随を明記しており、3.1.1の親POMもspring-boot-starter-parent 4.1.0です。Spring Boot 4.1で使うなら3.1.x、と読んでかまいません。2.x系の2.9.1はSpring Boot 3.5.16に対してビルドされています。Spring Boot 3.5のOSSサポートは2026年6月30日に終わっているため、2.x系は延命用と考えるのが妥当です。Spring Boot側の期限はSpring Bootバージョン一覧とサポート期限（EOL）で確認できます。

Maven Centralで「springdoc」を検索すると、org.springdoc:spring-boot-springdocの3.1.2が上位に出ることがあります。これはPOMの説明が「Project for Springdoc integration」の検証用artifactで、Maven Central上のファイルは2020年5月6日から更新されていません。本体の版ではありません。

系列を取り違えたときの症状（実測）

同じコントローラーを持つアプリで、Spring Bootとspringdocの組み合わせだけを変えて起動しました（JDK 25、Maven 3.9.11）。

Spring Boot 4に2.9.1を入れた場合の最下層の例外は次のとおりです。Spring Boot 4でWebMvcPropertiesが別パッケージへ移ったため、2.x系のSwaggerConfigがクラスを見つけられません。

Caused by: java.lang.TypeNotPresentException: Type org.springframework.boot.autoconfigure.web.servlet.WebMvcProperties not present
Caused by: java.lang.ClassNotFoundException: org.springframework.boot.autoconfigure.web.servlet.WebMvcProperties

逆にSpring Boot 3.5に3.1.1を入れると、org/springframework/boot/web/context/servlet/ApplicationServletEnvironmentのNoClassDefFoundErrorで止まります。いちばん気づきにくいのは1.8.0の組み合わせです。エラーもログも出ずに起動し、springdocの自動設定が読まれないまま、Swagger UIとAPI定義のURLが404を返します（業務APIは動きます）。Spring Bootを上げた後にSwagger UIだけが404になったら、まず依存関係に旧名のspringdoc-openapi-uiが残っていないかを確かめてください。

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

Spring Boot 4（Spring MVC）の場合、Mavenはpom.xmlに次の1つを足します。Spring Boot 3ならversionを2.9.1にします。

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

Gradleは次の1行です。

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

Spring Initializrが生成するSpring Boot 4のプロジェクトでは、Web機能の依存名がspring-boot-starter-webからspring-boot-starter-webmvcに変わっています（Spring Boot 4での依存名の変更はSpring Bootとは｜4.1系の依存名の変更と最小Web APIの作り方を参照）。springdoc側の依存名は2.x系から変わっていません。用途に応じたstarterは次のとおりです。

WebFluxで組んでいる場合はSpring WebFluxとは？MVCとの違いのとおりスタックが別なので、-webmvc-を-webflux-に置き換えます。定義ファイルだけを外部ツールに渡し、画面は不要という構成なら-apiで足ります。

Swagger UIとapi-docsのURL

依存関係を足して起動すると、設定なしで次のパスが有効になります。ポート8080ならhttp://localhost:8080/v3/api-docsのように開きます。

3.1.1では起動時に「SpringDoc /v3/api-docs endpoint is enabled by default. To disable it in production, set the property ‘springdoc.api-docs.enabled=false’」という警告が出ます。不具合ではなく、本番で公開したままにしないための注意喚起です。

出力されるOpenAPIの版は既定で3.1.0です（CHANGELOGによると2025年1月3日の2.8.0で3.1が既定になりました）。古いコード生成ツールなどが3.1を読めない場合は、springdoc.api-docs.version=openapi_3_0を設定すると"openapi":"3.0.1"で出力されました。生成した定義からクライアントコードを作るなら、OpenAPI Generatorの使い方とMaven設定側の対応版も合わせて確認してください。

アノテーションと設定クラスの記述例

次のコントローラー（BookController.java）と設定クラス（OpenApiConfig.java）で、タグ・要約・パラメーター説明・スキーマ例・Bearer認証の定義まで出力できます。2つは別ファイルで、import文は省略しています。@Validや@NotBlankを使うので、spring-boot-starter-validationも依存に入れてください。Javaのrecordにもそのまま使えます。

@RestController
@RequestMapping("/api/books")
@Tag(name = "books", description = "書籍の参照と登録")
public class BookController {

    public record Book(
            @Schema(description = "書籍ID", example = "42") long id,
            @Schema(description = "タイトル", example = "Spring入門") String title) {}

    public record CreateBookRequest(
            @NotBlank @Size(max = 100)
            @Schema(description = "タイトル", example = "Spring入門") String title) {}

    @Operation(summary = "書籍を1件取得する")
    @ApiResponse(responseCode = "200", description = "取得できた")
    @ApiResponse(responseCode = "404", description = "該当なし", content = @Content)
    @GetMapping("/{id}")
    public ResponseEntity<Book> get(@Parameter(description = "書籍ID") @PathVariable long id) {
        return id == 42 ? ResponseEntity.ok(new Book(42, "Spring入門")) : ResponseEntity.notFound().build();
    }

    @Operation(summary = "書籍を登録する")
    @PostMapping
    public Book create(@Valid @RequestBody CreateBookRequest req) {
        return new Book(1, req.title());
    }
}

@Configuration
public class OpenApiConfig {
    @Bean
    OpenAPI apiInfo() {
        return new OpenAPI()
                .info(new Info().title("Book API").version("v1"))
                .components(new Components().addSecuritySchemes("bearerAuth",
                        new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")))
                .addSecurityItem(new SecurityRequirement().addList("bearerAuth"));
    }
}

Bean Validationの制約もスキーマに反映されます。CreateBookRequestのtitleはrequiredに入り、@Size(max = 100)は"maxLength":100,"minLength":0になりました。@NotBlankからはminLength:1が出ない点は、仕様として受け取る側に伝えておく必要があります。@Tagを付けないと、タグ名はクラス名から自動で付きます。なおOpenApiConfigのBearer認証は「定義にこう記載する」という宣言で、実際の認証処理はしません。後述のSpring Securityの例はHTTP Basicなので、同じアプリで使うなら定義側の認証方式も実装に合わせてください。

エラー応答だけを書いたときの200応答の欠落

上のコードから@ApiResponse(responseCode = "200", …)の行を消し、404のcontent = @Contentも外して@ApiResponse(responseCode = "404", description = "該当なし")だけにすると、生成された定義のresponsesは404の1件だけになりました。正常系の200が定義から消え、しかも404側にBookのスキーマが付きます。この例では、メソッドに書いた@ApiResponseが戻り値から推測される200応答に置き換わった形です。

// 404だけを書いた場合の responses
{"404": {"description": "該当なし", "content": {"*/*": {"schema": {"$ref": "#/components/schemas/Book"}}}}}

// 200と404を書き、404に content = @Content を付けた場合
{"200": {"description": "取得できた", "content": {"*/*": {"schema": {"$ref": "#/components/schemas/Book"}}}},
 "404": {"description": "該当なし"}}

エラー応答を書き足すときは、200も明示し、本文の無い応答にはcontent = @Contentを付けます。Swagger UIでは応答の一覧を開かないと気づきにくく、見落とすと定義から生成したクライアントの戻り値の型が実装と合わなくなるおそれがあります。

MockMvcTesterによる応答コードの検証

定義の崩れはテストで止められます。Spring Boot 4のMockMvcTesterで/v3/api-docsを読み、200と404の応答コードが定義にあるかだけを確かめるテストです。404だけ（content = @Contentなし）を書いた版では失敗し、200と404を書いた版では成功しました。

@SpringBootTest
@AutoConfigureMockMvc
class ApiDocsTest {
    @Autowired
    MockMvcTester mvc;

    @Test
    void getBookDocumentsSuccessResponse() {
        assertThat(mvc.get().uri("/v3/api-docs"))
                .hasStatusOk()
                .bodyJson()
                .extractingPath("$.paths['/api/books/{id}'].get.responses")
                .asMap()
                .containsKeys("200", "404");
    }
}

Spring Boot 4ではAutoConfigureMockMvcのパッケージがorg.springframework.boot.webmvc.test.autoconfigureに移り、テスト用の依存はspring-boot-starter-webmvc-testです。

application.propertiesでよく使う設定

設定はすべてspringdoc.で始まります。既定値は公式のプロパティ一覧の記載です。

springdoc.swagger-ui.path=/docsとspringdoc.api-docs.path=/openapiに変えると、/docsは/swagger-ui/index.htmlへの302になり、元の/swagger-ui.htmlと/v3/api-docsは404になりました。画面の実体は/swagger-ui/index.htmlのまま残るので、URLを変えても隠したことにはなりません。

本番で無効化するときの2つのプロパティの違い

本番プロファイルで止めるとき、どちらのプロパティを使うかで結果が変わります。実測の応答は次のとおりです。

画面だけを消すと、全エンドポイントとスキーマを列挙したJSONは公開されたままです。本番で止めるならapplication-prod.propertiesにspringdoc.api-docs.enabled=falseを書きます。両方を書いても害はありません。

Spring SecurityによるSwagger UIとAPI定義の保護

本番でも社内向けにだけ見せたい場合は、Spring Securityで画面の入口・画面の実体・JSON定義・YAML定義の4種類のパスをまとめて守ります。/swagger-ui.htmlだけを守っても、画面の実体と定義が別のパスにあるためです。

@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth
                    .requestMatchers("/swagger-ui.html", "/swagger-ui/**",
                            "/v3/api-docs", "/v3/api-docs/**", "/v3/api-docs.yaml").hasRole("DOCS")
                    .anyRequest().authenticated())
            .httpBasic(Customizer.withDefaults());
    return http.build();
}

Spring Boot 4.1.1で試した結果、5つのURL（/swagger-ui.html、/swagger-ui/index.html、/v3/api-docs、/v3/api-docs.yaml、/v3/api-docs/swagger-config）は、未認証で401、DOCSロールの無いユーザーで403、DOCSロールのユーザーで302または200になりました。注意したいのは/v3/api-docs.yamlで、/v3/api-docs/**だけを指定した設定では一致せず、DOCSロールの無いログインユーザーにもYAML定義が200で返りました（JSONは403）。YAMLのパスは明示してください。開発中だけ全員に開けたいならhasRoleをpermitAll()に替えます。フィルタの評価順はSecurityFilterChainとは？フィルタ実行順序と設定例で解説しています。

3.x系のMCP連携：AIエージェント向けの公開設定とアクセス制御

3.x系には、@RestControllerのエンドポイントをMCP（Model Context Protocol）のツールとしてAIエージェントに公開する機能があります（公式ドキュメントのMCP Support）。専用starterは3.0.3で追加され、Maven Centralに2.x系の版はありません。3.1.0でSpring AI 2.0.0に追随しています。/mcpの受け口そのものはSpring AIのMCPサーバーstarterが提供するため、2つの依存を足します。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    <version>2.0.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-mcp</artifactId>
    <version>3.1.1</version>
</dependency>

spring.ai.mcp.server.protocol=streamable
springdoc.ai.mcp.enabled=true

前述のBookControllerで試すと、起動ログに「Registered 2 MCP tool callbacks from OpenAPI specification」と出て、MCPのtools/listにgetとcreateの2つが並びました。ツールの説明は@Operationのsummaryに戻り値の型を足した「書籍を登録する. Returns Book (id, title)」で、入力スキーマはOpenAPI定義から作られます。getを{"id":42}で呼ぶと実際にAPIが呼ばれ、{"id":42,"title":"Spring入門"}が返りました。

POSTのcreateは実行されず、"requires_human_approval":trueを含む応答が返りました。GET・HEAD・OPTIONS以外を「変更系」と見なし、人の承認を挟むのが既定です（springdoc.ai.mcp.guardrails.require-approval-for-mutating-tools=true）。

この機能は、社内のAIエージェントに既存の業務APIを読ませたいときに向いています。インターネットに出ているAPIへ、認証なしで有効化してはいけません。公式ドキュメントは、/mcp・/mcp-ui・/api/mcp-admin/**が独自の認証・認可を一切持たないこと、承認の手順は確認のためのもので、呼び出し元が自分で承認できてしまうためアクセス制御にはならないことを明記しています。前章と同じSecurityFilterChainでこの3パスを守ってから有効化してください。

3.1.1のリリースノートでは、7件のセキュリティ勧告が修正され、うち5件がMCP周り（パスパラメーターのエンコード漏れ、管理画面の既定公開、監査ログへの認証情報の記録など）でした。あわせて、starterを足すだけで/mcpが公開されていた挙動が、springdoc.ai.mcp.enabled=trueを書くまで何も登録しない方式に変わっています。3.1.0でMCPを試した環境は3.1.1へ上げてください。実測では、springdoc.ai.mcp.enabledを書かない状態でもSpring AIのstarterが/mcpを200で受け付け、ツール一覧が空で返りました。springdoc側の既定が無効でも、Spring AIのstarterを入れた時点で受け口は開いていると考えて守る必要があります。

2.9.1と3.1.1は同日に公開され、Swagger UIに同梱されたDOMPurifyのXSS対応（Swagger UI 5.32.14への更新）と、Accept-Languageごとに定義をキャッシュすることによるメモリ枯渇の修正（springdoc.cache.max-entries、既定100）を両系列とも含みます。MCPを使わない場合も、それより前のパッチ版からは上げておくのが安全です。

Swagger UIが表示されないときの確認順

Swagger UIが出ないときは、症状から原因を次の表で切り分けます。上の2行は前述の実測で再現した組み合わせです。

コンテキストパス（server.servlet.context-path）を設定しているアプリでは、URLの先頭にそのパスが付きます。/swagger-ui.htmlで404でも、/app/swagger-ui.htmlなら開く、というケースです。

SpringFoxから移行する手順

SpringFoxとSwagger 2のアノテーションを依存から外し、springdoc-openapi-starter-webmvc-uiを足したうえで、アノテーションを置き換えます。対応は公式の移行ガイドのとおりです。

パッケージはio.swagger.v3.oas.annotationsに変わります。DocketのBeanを複数定義していた場合だけ、GroupedOpenApiのBeanに置き換えます（1つだけなら削除してプロパティに移します）。@ApiResponseを書き換えるときは、前述の「200が消える」挙動に注意してください。SpringFoxでは補われていた正常系の応答が、Springdocでは書かない限り出ません。

Spring BootでのAPI開発や、既存APIの仕様書整備・外部連携の設計を外部に頼みたい場合は、弊社のAPI開発・システム連携の支援でも対応しています。

よくある質問

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

Apache License 2.0のオープンソースで、商用利用も無料です。受託開発の成果物にも組み込めます。再配布するときは、ライセンス文の同梱、NOTICEファイルがあればその内容の表示、改変したファイルへの変更表示といったApache License 2.0第4項の条件を守ります。

Spring Boot 4でspringdoc-openapi-starter-webmvc-uiは使えますか？

使えます。artifactIdは2.x系と同じspringdoc-openapi-starter-webmvc-uiで、版を3.x系（2026年10月時点で3.1.1）にします。2.x系のままだとWebMvcPropertiesのClassNotFoundExceptionで起動しません。

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

前者はSpring Boot 2向けの1.x系（最終1.8.0）、後者はSpring Boot 3以降向けの2.x・3.x系です。Spring Boot 3・4で前者を使うと、エラーが出ないままSwagger UIとAPI定義のURLが404になります。

OpenAPI 3.0形式で出力できますか？

できます。springdoc.api-docs.version=openapi_3_0を設定すると"openapi":"3.0.1"で出力されます。既定は3.1.0です。

最新バージョンはどこで確認できますか？

Maven Centralのspringdoc-openapi-starter-webmvc-uiのページか、GitHubのReleasesで確認します。2.x系と3.x系は同じ日に並んで公開されることが多く、2026年9月6日には2.9.1と3.1.1が出ました。公式サイトのFAQにある互換表は更新が遅れることがあります。

関連記事

• OpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方｜3.0・3.1・3.2の差分
• Spring Boot 4とは？最新バージョン4.1の変更点・新機能とSpring Boot 3との違い【2026年10月】
• Spring Bootバージョン一覧とサポート期限（EOL）【2026年10月】最新版は4.1、4.0の無償サポートは12月末終了
• OpenAPI Generatorとは？使い方・生成されるコード・Maven設定を実行例で解説
• SecurityFilterChainとは？Spring Securityのフィルタ実行順序と設定例【Spring Security 7.1対応】