springdoc-openapiの使い方｜Swagger UIとアノテーション一覧

springdoc-openapi は、Spring Boot のコントローラーを読み取って、OpenAPI（API の仕様を書く標準の形式）の JSON と、ブラウザで試せる画面（Swagger UI）を自動で作るライブラリです。 依存を1つ足すだけで、次の URL が開けるようになります。

Spring Boot 4 では springdoc-openapi 3.x を使います。 2.x（Boot 3 用）や 1.x（Boot 2 用、springdoc-openapi-ui）のままでは対応していません。

確認環境：springdoc-openapi 3.1.1（GitHub のリリースで最新の版。2026年9月6日公開。Spring Boot 4.1.0 でビルドされ、swagger-core 2.2.55・swagger-ui 5.32.14 を使用）と Spring Boot 4.1.1。対応表・設定名・既定値・URL は、springdoc.org の FAQ と README、タグ v3.1.1 のソース（Constants・SpringDocConfigProperties）とテストで確かめました。この記事のコントローラーのアノテーションは、swagger-annotations 2.2.55 のソースと一緒に javac（OpenJDK 21.0.10）でコンパイルして、属性名と付けられる場所が正しいことを確かめています。Swagger UI のエラー表示は、swagger-ui 5.32.14 と swagger-client 3.38.2 のソースで確かめました（確認日 2026年10月13日）。

依存の追加

build.gradle.kts

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-webmvc")
    implementation("org.springframework.boot:spring-boot-starter-validation")
    implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:3.1.1")
}

pom.xml

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

springdoc は Spring Boot が版を管理するライブラリではないので、版を自分で書きます。 Boot 4 の starter の名前（spring-boot-starter-webmvc など）は、関連記事「Spring Boot starter一覧｜用途別の選び方とBoot 4の新旧対応表」で扱っています。

starter の選び方

3.x には、この他に MCP（AI から API を呼ぶしくみ）用の starter もあります。3.1.1 の変更履歴によると、MCP は springdoc.ai.mcp.enabled=true を入れたときだけ動く形に変わりました。

起動して開く

アプリを起動して、ブラウザで http://localhost:8080/swagger-ui.html を開きます。springdoc のテストでは、/swagger-ui.html への GET は 302 で Location: /swagger-ui/index.html が返ることを確かめています。JSON は http://localhost:8080/v3/api-docs です。3.x の既定では、出力される OpenAPI の版は 3.1（設定の既定値 OPENAPI_3_1）です。

完成コード：アノテーションを付けたコントローラー

アノテーションが無くても、springdoc はメソッドの引数・戻り値・@Valid の制約から仕様を作ります。 アノテーションは、説明・例・エラー時の応答・認証を足すために使います。

OpenApiConfig.java（API 全体の情報と JWT の定義）

package com.example.demo;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.annotations.servers.Server;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(
        info = @Info(title = "User API", version = "v1", description = "ユーザー管理の API"),
        servers = @Server(url = "http://localhost:8080", description = "ローカル"))
@SecurityScheme(
        name = "bearerAuth",               // @SecurityRequirement(name = ...) で参照する名前
        type = SecuritySchemeType.HTTP,
        scheme = "bearer",
        bearerFormat = "JWT")
public class OpenApiConfig {
}

UserRequest.java・UserResponse.java（DTO）

package com.example.demo;

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

@Schema(description = "ユーザー登録のリクエスト")
public record UserRequest(
        @Schema(description = "氏名", example = "山田 太郎", requiredMode = Schema.RequiredMode.REQUIRED)
        @NotBlank @Size(max = 50)
        String name,

        @Schema(description = "メールアドレス", example = "taro@example.com")
        @Email
        String email) {
}

package com.example.demo;

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "ユーザー")
public record UserResponse(
        @Schema(description = "ID", example = "1", accessMode = Schema.AccessMode.READ_ONLY)
        Long id,
        @Schema(description = "氏名", example = "山田 太郎")
        String name,
        @Schema(description = "メールアドレス", example = "taro@example.com")
        String email) {
}

UserController.java

package com.example.demo;

import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import java.util.List;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;

@Tag(name = "Users", description = "ユーザーの登録・取得")
@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "ユーザーを1件取得", description = "ID を指定してユーザーを返します。")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "見つかった"),
            @ApiResponse(responseCode = "404", description = "見つからない",
                    content = @Content(schema = @Schema(hidden = true)))
    })
    @GetMapping("/{id}")
    public UserResponse get(
            @Parameter(description = "ユーザーID", example = "1") @PathVariable Long id) {
        return new UserResponse(id, "山田 太郎", "taro@example.com");
    }

    @Operation(summary = "ユーザーを検索")
    @GetMapping
    public List<UserResponse> search(
            @Parameter(description = "氏名の部分一致") @RequestParam(required = false) String name) {
        return List.of();
    }

    @Operation(summary = "ユーザーを登録", security = @SecurityRequirement(name = "bearerAuth"))
    @ApiResponse(responseCode = "201", description = "登録した")
    @ApiResponse(responseCode = "400", description = "入力エラー", content = @Content)
    @ResponseStatus(HttpStatus.CREATED)
    @PostMapping
    public UserResponse create(@Valid @RequestBody UserRequest request) {
        return new UserResponse(1L, request.name(), request.email());
    }

    @Hidden   // ドキュメントに出さない
    @GetMapping("/internal/ping")
    public String ping() {
        return "pong";
    }
}

@ApiResponse は、@ApiResponses({...}) でまとめても、メソッドに何個も並べても書けます（どちらもコンパイルが通りました）。content = @Content と空にすると、その応答には本文の型が付きません。 書かないと、メソッドの戻り値の型（ここでは UserResponse）が付きます。

入力チェックとエラー処理を含めた REST API の作り方は、関連記事「Spring BootでREST APIを作る｜入力チェック・エラー処理・テストまで」で、@NotBlank などの一覧は、関連記事「Spring Bootバリデーション一覧｜@Validと@Validated」で扱っています。

アノテーション早見表

パッケージはすべて io.swagger.v3.oas.annotations の下です（swagger-annotations 2.2.55 のソースで確認）。

どこに付けて、何を書くか

@RequestBody は Spring（org.springframework.web.bind.annotation）と swagger（io.swagger.v3.oas.annotations.parameters）に同じ名前があります。 本文を受け取るのは Spring の方です。swagger の方は説明を足すだけなので、両方使うときは完全修飾名で書き分けます。

@Schema の属性

試した結果の形（springdoc のテストの期待値）

springdoc 3.1.1 のソースにあるテスト（app45）では、次のコードから下の JSON が出ることを確かめています。

@OpenAPIDefinition(info = @Info(title = "My App", description = "Some long and useful description", version = "v1",
        license = @License(name = "Apache 2.0", url = "https://www.apache.org/licenses/LICENSE-2.0")))
@SecurityScheme(name = "bearer", type = SecuritySchemeType.HTTP, scheme = "bearer", bearerFormat = "JWT")
public class OpenApiConfig { }

@Tag(name = "People", description = "Use this resource to serve all requests and initiate all operations related to people")
@RestController
@RequestMapping(value = "/v1/people")
public class HelloController {
    @Operation(description = "List all persons")
    @SecurityRequirement(name = "bearer")
    @ApiResponse(responseCode = "200", description = "", content = @Content(array = @ArraySchema(schema = @Schema(implementation = PersonDTO.class))))
    @GetMapping(path = "/list", consumes = MediaType.ALL_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
    public List<PersonDTO> list() { ... }
}

{
  "openapi": "3.1.0",
  "paths": {
    "/v1/people/list": {
      "get": {
        "tags": ["People"],
        "description": "List all persons",
        "operationId": "list_1",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PersonDTO" } }
              }
            }
          }
        },
        "security": [ { "bearer": [] } ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
    }
  }
}

（info・servers・tags・schemas は省いています）

@ApiResponse の description を空（""）にすると、"OK" が入っていました。 DTO は components.schemas に1回だけ定義され、各 API からは $ref で参照されます。

OpenAPI の YAML を手で書く方法は、関連記事「OpenAPIの書き方｜YAMLのテンプレートとチームで使う運用」で、設計書としてまとめる方法は、関連記事「API設計書の書き方｜Markdown・OpenAPIテンプレートと記入例」で扱っています。

JWT の Authorize ボタンを出す

Swagger UI の右上に「Authorize」ボタンを出すには、認証方式（@SecurityScheme）を定義します。 上の OpenApiConfig のように、type = HTTP・scheme = "bearer"・bearerFormat = "JWT" を書きます。

ボタンを押すとトークンの入力欄が出ます。Bearer は付けずに、トークンだけを入れます。 Swagger UI が Authorization: Bearer <トークン> の形でヘッダーを付けて送ります。

アノテーションではなく、Bean で書く方法もあります（springdoc の FAQ の例）。

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .components(new Components()
                    .addSecuritySchemes("bearer-key",
                            new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
}

この場合の OpenAPI・Components・SecurityScheme は、io.swagger.v3.oas.models パッケージのクラスです（アノテーションの SecurityScheme とは別物）。JWT の発行と検証は、関連記事「Spring Security JWT認証の実装｜Boot 4対応の設定コード全文」で、JWT そのものの注意点は、関連記事「JWTとは｜仕組みと、安全に使うための注意点」で扱っています。

Spring Security で弾かれるとき

Spring Security を入れると、/swagger-ui.html も /v3/api-docs もログインが要る状態になります。 Swagger UI の画面だけ開けても、JSON の取得で弾かれると、画面には次の表示が出ます。

Failed to load API definition.
Errors
Fetch error
response status is 401 /v3/api-docs

swagger-client のソースでは、エラー文は「サーバーが返した理由の文字列（Unauthorized など）、それが無ければ response status is <番号>」に、取得した URL を足した形です。401 はログインが要る、403 は権限が無い、という意味です。

次の3つのパスを許可します。

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(
                    "/v3/api-docs/**",     // JSON・YAML・swagger-config・グループ
                    "/v3/api-docs.yaml",
                    "/swagger-ui/**",      // 画面の HTML・JS・CSS
                    "/swagger-ui.html"     // 入口（転送元）
                ).permitAll()
                .anyRequest().authenticated())
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

本番で公開したくない場合は、permitAll() にせず、ドキュメントそのものを止めます（次の章）。SecurityFilterChain の書き方は、関連記事「Spring Security入門｜SecurityFilterChainとDB認証」で扱っています。

本番で無効にする設定

FAQ には「springdoc.swagger-ui.enabled=false は UI だけを無効にする」とあります。本番で両方止めるなら、2つとも false にします。 プロファイルで分ける例です。

# application-prod.yml
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

# application-dev.yml
springdoc:
  swagger-ui:
    persist-authorization: true
    operations-sorter: method
    tags-sorter: alpha

プロファイルの切り替え方は、関連記事「Spring Bootプロファイル切り替え｜application.ymlと優先順位」で扱っています。

よく使う springdoc.* 設定

SpringDocConfigProperties・SwaggerUiConfigProperties（タグ v3.1.1 のソース）から、よく使うものを並べました。

springdoc.cache.max-entries（既定 100）は 3.1.1 で追加されました。

API をグループに分ける（GroupedOpenApi）

利用者向けと管理者向けのように、ドキュメントを分けられます。 各グループは /v3/api-docs/{グループ名} で出て、Swagger UI の右上に切り替えのリストが出ます。

package com.example.demo.config;

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiGroupConfig {

    @Bean
    GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public")                 // /v3/api-docs/public
                .pathsToMatch("/api/**")
                .pathsToExclude("/api/admin/**")
                .build();
    }

    @Bean
    GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin")                  // /v3/api-docs/admin
                .pathsToMatch("/api/admin/**")
                .build();
    }
}

FAQ には「グループごとに一意の groupName を付ける」「パスとパッケージの組み合わせで分けられる」とあります。設定ファイルでも書けます。

springdoc:
  group-configs:
    - group: public
      paths-to-match: /api/**
    - group: admin
      paths-to-match: /api/admin/**

よくあるエラーと原因

CORS で別のオリジンから JSON を読む場合は、関連記事「Spring Boot CORS設定｜3つの書き方とSecurity併用のコード全文」で扱っています。

よくある質問

Q. SpringFox（@EnableSwagger2）から移るには？ A. springdoc の公式サイトに移行の手順があります。依存を springdoc-openapi-starter-webmvc-ui に替え、アノテーションを次のように置き換えます。@Api → @Tag、@ApiOperation(value, notes) → @Operation(summary, description)、@ApiParam・@ApiImplicitParam → @Parameter、@ApiModel・@ApiModelProperty → @Schema、@ApiIgnore → @Hidden など、@ApiResponse(code = 404, message = …) → @ApiResponse(responseCode = "404", description = …)。Docket の Bean が複数あるときは GroupedOpenApi に、1つだけなら消して springdoc.packages-to-scan・paths-to-match で絞ります。

Q. OpenAPI 3.0 で出したいです。 A. springdoc.api-docs.version=openapi_3_0 で 3.0 の形になります。既定は 3.1 です。

Q. 生成した JSON をファイルとして保存して、レビューしたいです。 A. 起動したアプリから /v3/api-docs.yaml を取得してリポジトリに置く方法があります。springdoc.writer-with-order-by-keys=true にすると、キーの順が固定されて差分が読みやすくなります。

Q. Actuator のエンドポイントも載せたいです。 A. springdoc.show-actuator=true で載ります。Actuator の公開範囲は、関連記事「Spring Boot Actuator設定｜エンドポイント一覧と公開設定の雛形」で扱っています。

まとめ

• Boot 4 は springdoc 3.x（最新 3.1.1）。依存は springdoc-openapi-starter-webmvc-ui、版は自分で書く
• 画面は /swagger-ui.html（/swagger-ui/index.html へ転送）、JSON は /v3/api-docs
• 説明は @Tag・@Operation・@Parameter・@Schema・@ApiResponse。@Schema(required) は非推奨で requiredMode
• JWT は @SecurityScheme(type = HTTP, scheme = "bearer", bearerFormat = "JWT") と @SecurityRequirement の name をそろえる
• Security では /v3/api-docs/**・/swagger-ui/**・/swagger-ui.html を許可。本番は api-docs.enabled と swagger-ui.enabled を false

参考・出典

確認日はいずれも 2026年10月13日です。

• springdoc-openapi 公式サイト：https://springdoc.org/
• springdoc-openapi FAQ：https://springdoc.org/faq.html
• springdoc-openapi（GitHub、README・CHANGELOG・ソースとテスト、タグ v3.1.1）：https://github.com/springdoc/springdoc-openapi
• springdoc-openapi リリース一覧：https://github.com/springdoc/springdoc-openapi/releases
• swagger-core（GitHub、swagger-annotations、タグ v2.2.55）：https://github.com/swagger-api/swagger-core
• swagger-ui（GitHub、タグ v5.32.14）：https://github.com/swagger-api/swagger-ui
• swagger-js（swagger-client、GitHub）：https://github.com/swagger-api/swagger-js
• OpenAPI Specification 3.1.0：https://spec.openapis.org/oas/v3.1.0

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。