spring-boot-openapi-documentation

SpringDoc による Spring Boot OpenAPI ドキュメント

概要

SpringDoc OpenAPI は、Spring Boot プロジェクト向けに OpenAPI 3.0 ドキュメントを自動生成し、API の確認やテストに使える Swagger UI のウェブインターフェースを提供します。

使用する場面

• Spring Boot 3.x プロジェクトで SpringDoc OpenAPI をセットアップする
• REST API 用の OpenAPI 3.0 仕様を生成する
• Swagger UI を設定、カスタマイズする
• アノテーションを使って詳細な API ドキュメントを追加する
• バリデーションを含むリクエスト／レスポンスモデルをドキュメント化する
• API セキュリティのドキュメント（JWT、OAuth2、Basic Auth）を実装する
• ページネーションやソートに対応したエンドポイントをドキュメント化する
• API エンドポイントに例とスキーマを追加する
• OpenAPI 定義をプログラムでカスタマイズする
• 複数の API グループとバージョンに対応する
• エラーレスポンスと例外ハンドラーをドキュメント化する
• API ドキュメントに JSR-303 Bean Validation を追加する
• Kotlin ベースの Spring Boot API に対応する

クイックリファレンス

概念	説明
依存関係	WebMvc には springdoc-openapi-starter-webmvc-ui、WebFlux には springdoc-openapi-starter-webflux-ui
設定	springdoc.api-docs.* および springdoc.swagger-ui.* プロパティを含む application.yml
アクセス先	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 をカスタマイズする：フィルタリング、ソート、「試してみる」機能を有効にします
• API ドキュメントにバージョンを付ける：OpenAPI Info にバージョンを含めます

参考資料

• 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 公式ドキュメント
• OpenAPI 3.0 仕様
• Swagger UI の設定