Spring Boot OpenAPI Documentation with SpringDoc

Overview

SpringDoc OpenAPI は Spring Boot プロジェクトの OpenAPI 3.0 ドキュメント生成を自動化し、API の探索とテストのための Swagger UI Web インターフェイスを提供します。

使用する場合

• Spring Boot 3.x プロジェクトで SpringDoc OpenAPI をセットアップする
• REST API の OpenAPI 3.0 仕様を生成する
• Swagger UI を構成およびカスタマイズする
• アノテーションを使用して詳細な API ドキュメントを追加する
• バリデーション付きでリクエスト/レスポンスモデルをドキュメント化する
• API セキュリティドキュメント (JWT、OAuth2、Basic Auth) を実装する
• ページング可能およびソート可能なエンドポイントをドキュメント化する
• API エンドポイントに例とスキーマを追加する
• プログラムで OpenAPI 定義をカスタマイズする
• 複数の API グループとバージョンをサポートする
• エラーレスポンスと例外ハンドラーをドキュメント化する
• JSR-303 Bean Validation を API ドキュメントに追加する
• Kotlin ベースの Spring Boot API をサポートする

クイックリファレンス

概念	説明
依存関係	WebMvc 向け springdoc-openapi-starter-webmvc-ui、WebFlux 向け springdoc-openapi-starter-webflux-ui
設定	application.yml で springdoc.api-docs.* と springdoc.swagger-ui.* プロパティを使用
アクセスポイント	OpenAPI JSON: /v3/api-docs、Swagger UI: /swagger-ui/index.html
コアアノテーション	@Tag、@Operation、@ApiResponse、@Parameter、@Schema、@SecurityRequirement
セキュリティ	OpenAPI Bean でセキュリティスキームを構成し、@SecurityRequirement で適用
ページング	Spring Data の Pageable で @ParameterObject を使用

手順

1. 依存関係を追加

アプリケーションタイプ (WebMvc または WebFlux) に応じて SpringDoc スターターを追加します。Maven/Gradle の設定については dependency-setup.md を参照してください。

2. SpringDoc を構成

application.yml に基本的な構成を設定します。

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method

詳細なオプションについては configuration.md を参照してください。

3. コントローラーをドキュメント化

OpenAPI アノテーションを使用して説明情報を追加します。

@RestController
@Tag(name = "Book", description = "Book management APIs")
public class BookController {

    @Operation(summary = "Get book by ID")
    @ApiResponse(responseCode = "200", description = "Book found")
    @GetMapping("/{id}")
    public Book findById(@PathVariable Long id) { }
}

パターンについては controller-documentation.md を参照してください。

4. モデルをドキュメント化

DTO に @Schema アノテーションを適用します。

@Schema(description = "Book entity")
public class Book {
    @Schema(example = "1", accessMode = Schema.AccessMode.READ_ONLY)
    private Long id;

    @Schema(example = "Clean Code", required = true)
    private String title;
}

バリデーションパターンについては model-documentation.md を参照してください。

5. セキュリティを構成

OpenAPI Bean でセキュリティスキームをセットアップします。

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

@SecurityRequirement(name = "bearer-jwt") でコントローラーに適用します。security-configuration.md を参照してください。

6. ページングをドキュメント化

Spring Data の Pageable で @ParameterObject を使用します。

@GetMapping("/paginated")
public Page<Book> findAll(@ParameterObject Pageable pageable) {
    return repository.findAll(pageable);
}

pagination-support.md を参照してください。

7. ドキュメントをテスト

/swagger-ui/index.html で Swagger UI にアクセスしてドキュメントの完成度を確認します。

8. 本番環境用にカスタマイズ

API グループ化、バージョニング、ビルドプラグインを構成します。advanced-configuration.md と build-integration.md を参照してください。

ベストプラクティス

• 説明的なオペレーション要約を使用: 短い (< 120 文字) で明確なステートメント
• すべてのレスポンスコードをドキュメント化: 成功 (2xx)、クライアントエラー (4xx)、サーバーエラー (5xx) を含める
• リクエスト/レスポンス本体に例を追加: @ExampleObject を使用して現実的な例を追加
• JSR-303 バリデーションアノテーションを活用: SpringDoc はバリデーションアノテーションから制約を自動生成
• 複雑なパラメーターに @ParameterObject を使用: 特に Pageable やカスタムフィルターオブジェクト向け
• @Tag で関連エンドポイントをグループ化: ドメインエンティティまたはフィーチャー別に API を整理
• セキュリティ要件をドキュメント化: 認証が必要な場合 @SecurityRequirement を適用
• 内部エンドポイントを適切に非表示: @Hidden を使用するか別の API グループを作成
• Swagger UI をカスタマイズして UX を向上: フィルタリング、ソート、試行機能を有効化
• API ドキュメントのバージョン管理: OpenAPI Info にバージョンを含める

References

• dependency-setup.md — Maven/Gradle 依存関係とバージョン選択
• configuration.md — 基本的な設定と詳細な設定オプション
• controller-documentation.md — コントローラーとエンドポイントのドキュメント化パターン
• model-documentation.md — エンティティ、DTO、バリデーションのドキュメント化
• security-configuration.md — JWT、OAuth2、Basic Auth、API キーの構成
• pagination-support.md — Pageable、Slice、カスタムページング パターン
• advanced-configuration.md — API グループ、カスタマイザー、OpenAPI Bean 設定
• exception-handling.md — 例外ドキュメント化とエラーレスポンススキーマ
• build-integration.md — Maven/Gradle プラグインと CI/CD 統合
• complete-examples.md — コントローラー、エンティティ、設定の完全な例
• annotations-reference.md — 属性付きアノテーション完全リファレンス
• springdoc-official.md — 公式 SpringDoc ドキュメント
• troubleshooting.md — 一般的な問題と解決策

制約と警告

• API 例やスキーマの説明に機密データを公開しないでください
• OpenAPI アノテーションを最小限に保ってコントローラーコードの複雑さを避けます。可能な限りグローバル設定を使用してください
• 大規模な API 定義は Swagger UI のパフォーマンスに影響する可能性があります。ドメイン別に API をグループ化してください
• スキーマ生成は複雑なジェネリック型では正しく機能しない場合があります。明示的な @Schema アノテーションを使用してください
• DTO の循環参照は無限再帰を引き起こします。スキーマ生成を避けてください
• セキュリティスキームは @SecurityRequirement アノテーションを使用する前に正しく構成する必要があります
• 非表示のエンドポイント (@Operation(hidden = true)) はコード内で見えたままであり、他のドキュメント化ツールを通じてリークする可能性があります

例

基本的なコントローラードキュメント化

@RestController
@Tag(name = "Books", description = "Book management APIs")
@RequestMapping("/api/books")
public class BookController {

    @Operation(
        summary = "Get book by ID",
        description = "Retrieves detailed information about a specific book"
    )
    @ApiResponse(responseCode = "200", description = "Book found")
    @ApiResponse(responseCode = "404", description = "Book not found")
    @GetMapping("/{id}")
    public Book getBook(@PathVariable Long id) {
        return bookService.findById(id);
    }

    @Operation(summary = "Create new book")
    @SecurityRequirement(name = "bearer-jwt")
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Book createBook(@Valid @RequestBody CreateBookRequest request) {
        return bookService.create(request);
    }
}

バリデーション付きドキュメント化されたモデル

@Schema(description = "Book entity")
public class Book {
    @Schema(description = "Unique identifier", example = "1", accessMode = Schema.AccessMode.READ_ONLY)
    private Long id;

    @Schema(description = "Book title", example = "Clean Code", required = true)
    @NotBlank
    @Size(min = 1, max = 200)
    private String title;

    @Schema(description = "Author name", example = "Robert C. Martin")
    @NotBlank
    private String author;

    @Schema(description = "Price in USD", example = "29.99", minimum = "0")
    @NotNull
    @DecimalMin("0.0")
    private BigDecimal price;
}

セキュリティ構成

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("Book API")
            .version("1.0.0")
            .description("REST API for book management"))
        .components(new Components()
            .addSecuritySchemes("bearer-jwt", new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT"))
            .addSecuritySchemes("api-key", new SecurityScheme()
                .type(SecurityScheme.Type.APIKEY)
                .in(SecurityScheme.In.HEADER)
                .name("X-API-Key")));
}

関連スキル

• spring-boot-rest-api-standards — REST API 設計標準
• spring-boot-dependency-injection — 依存関係注入パターン
• unit-test-controller-layer — REST コントローラーのテスト
• spring-boot-actuator — 本番環境の監視と管理

外部リソース

• SpringDoc Official Documentation
• OpenAPI 3.0 Specification
• Swagger UI Configuration