Spring Boot REST APIのドキュメント自動生成 - SpringDocでOpenAPI仕様書とSwagger UIを導入する

REST APIの開発において、APIドキュメントの整備は開発効率とチーム間のコミュニケーションを大きく左右します。SpringDoc OpenAPIを使用することで、コードから自動的にOpenAPI仕様書を生成し、Swagger UIで視覚的にAPIを確認・テストできる環境を構築できます。本記事では、Spring Boot 3.x環境でのSpringDoc OpenAPIの導入から、アノテーションを活用した詳細なAPI説明の記述、実際のドキュメント運用までを解説します。

実行環境と前提条件

本記事の内容を実践するにあたり、以下の環境を前提としています。

項目	バージョン・要件
Java	17以上
Spring Boot	3.4.x
SpringDoc OpenAPI	2.8.x
ビルドツール	Maven または Gradle
IDE	VS Code（Extension Pack for Javaインストール済み）

また、本記事はSpring Boot REST API入門 - @RestControllerでCRUDエンドポイントを実装するの続編として、基本的なSpring Boot REST APIの実装経験があることを前提としています。

期待される学習成果

本記事を読み終えると、以下のことができるようになります。

SpringDoc OpenAPIの依存関係を追加し、Swagger UIを有効化できる
@Operation、@Parameter、@SchemaアノテーションでAPIの詳細説明を記述できる
Swagger UIを使用してAPIの動作確認とテストを実行できる
OpenAPI仕様書（JSON/YAML形式）をエクスポートし、外部ツールと連携できる
本番環境でのセキュリティ設定やカスタマイズを適用できる

OpenAPI仕様とSpringDoc OpenAPIの概要

OpenAPI仕様とは

OpenAPI仕様（旧Swagger仕様）は、REST APIを記述するための業界標準フォーマットです。OpenAPI 3.0以降では、以下の情報を構造化されたJSON/YAML形式で定義できます。

APIのエンドポイント（パス、HTTPメソッド）
リクエスト/レスポンスの形式とスキーマ
認証・認可の方式
サーバー情報とメタデータ

この仕様書を活用することで、以下のメリットが得られます。

ドキュメントの自動生成: コードと仕様書の同期が保たれる
クライアントSDKの生成: OpenAPI Generatorで各言語のクライアントコードを自動生成できる
モックサーバーの構築: 実装前にAPIの動作をシミュレートできる
テストの自動化: 仕様書に基づいたAPIテストを実行できる

SpringDoc OpenAPIとは

SpringDoc OpenAPIは、Spring Bootアプリケーションから自動的にOpenAPI仕様書を生成するライブラリです。主な特徴は以下の通りです。

Spring Boot 3.x完全対応: Jakarta EE 9（jakarta.*パッケージ）に対応
自動検出: @RestControllerや@RequestMappingから自動的にAPI定義を抽出
Swagger UI統合: 追加設定なしでSwagger UIを利用可能
Bean Validation連携: @NotNull、@Sizeなどのバリデーションアノテーションを自動認識
豊富なカスタマイズ: アノテーションやプロパティで詳細な制御が可能

SpringDoc OpenAPIの導入

依存関係の追加

Spring Boot 3.x（Spring MVC）プロジェクトにSpringDoc OpenAPIを導入するには、以下の依存関係を追加します。

Mavenの場合（pom.xml）:

1
2
3
4
5


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

Gradleの場合（build.gradle）:

1

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

この依存関係を追加するだけで、以下のエンドポイントが自動的に有効になります。

エンドポイント	説明
`/v3/api-docs`	OpenAPI仕様書（JSON形式）
`/v3/api-docs.yaml`	OpenAPI仕様書（YAML形式）
`/swagger-ui.html`	Swagger UI（リダイレクト）
`/swagger-ui/index.html`	Swagger UI（直接アクセス）

WebFluxプロジェクトの場合

Spring WebFlux（リアクティブ）プロジェクトでは、代わりに以下の依存関係を使用します。

1
2
3
4
5


<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.8.5</version>
</dependency>

動作確認

依存関係を追加したら、アプリケーションを起動して以下のURLにアクセスします。

http://localhost:8080/swagger-ui.html

既存のREST APIがあれば、自動的にドキュメントが生成されていることを確認できます。

アノテーションによるAPI説明の記述

SpringDoc OpenAPIでは、Swagger APIアノテーションを使用してAPIの詳細な説明を追加できます。これらのアノテーションはio.swagger.v3.oas.annotationsパッケージに含まれています。

@Operationアノテーション

@Operationアノテーションは、個々のAPIエンドポイントに説明を追加するために使用します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(
        summary = "ユーザー一覧を取得する",
        description = "登録されているすべてのユーザーをページネーション付きで取得します。"
    )
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "ユーザー一覧の取得に成功"),
        @ApiResponse(responseCode = "500", description = "サーバー内部エラー")
    })
    @GetMapping
    public List<UserResponse> getUsers() {
        // 実装
    }

    @Operation(
        summary = "ユーザーを新規登録する",
        description = "リクエストボディで受け取ったユーザー情報を登録します。"
    )
    @ApiResponses(value = {
        @ApiResponse(responseCode = "201", description = "ユーザーの登録に成功"),
        @ApiResponse(responseCode = "400", description = "リクエストの形式が不正"),
        @ApiResponse(responseCode = "409", description = "メールアドレスが既に使用されている")
    })
    @PostMapping
    public UserResponse createUser(@RequestBody UserRequest request) {
        // 実装
    }
}

@Operationの主な属性は以下の通りです。

属性	説明
`summary`	APIの概要（短い説明）
`description`	APIの詳細説明
`operationId`	操作の一意識別子
`tags`	APIのグループ化タグ
`deprecated`	非推奨フラグ
`hidden`	ドキュメントから非表示にする

@Parameterアノテーション

@Parameterアノテーションは、パスパラメータやクエリパラメータに説明を追加します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "指定したIDのユーザーを取得する")
    @GetMapping("/{id}")
    public UserResponse getUser(
        @Parameter(
            name = "id",
            description = "ユーザーの一意識別子",
            required = true,
            example = "123",
            in = ParameterIn.PATH
        )
        @PathVariable Long id
    ) {
        // 実装
    }

    @Operation(summary = "ユーザーを検索する")
    @GetMapping("/search")
    public List<UserResponse> searchUsers(
        @Parameter(description = "検索キーワード（名前またはメールアドレス）", example = "tanaka")
        @RequestParam(required = false) String keyword,

        @Parameter(description = "ページ番号（0始まり）", example = "0")
        @RequestParam(defaultValue = "0") int page,

        @Parameter(description = "1ページあたりの件数", example = "20")
        @RequestParam(defaultValue = "20") int size
    ) {
        // 実装
    }
}

@Schemaアノテーション

@Schemaアノテーションは、リクエスト/レスポンスのデータモデルに説明を追加します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.*;

@Schema(description = "ユーザー登録リクエスト")
public class UserRequest {

    @Schema(
        description = "ユーザー名（3文字以上50文字以下）",
        example = "田中太郎",
        minLength = 3,
        maxLength = 50,
        requiredMode = Schema.RequiredMode.REQUIRED
    )
    @NotBlank
    @Size(min = 3, max = 50)
    private String name;

    @Schema(
        description = "メールアドレス",
        example = "tanaka@example.com",
        format = "email",
        requiredMode = Schema.RequiredMode.REQUIRED
    )
    @NotBlank
    @Email
    private String email;

    @Schema(
        description = "年齢（0以上150以下）",
        example = "30",
        minimum = "0",
        maximum = "150"
    )
    @Min(0)
    @Max(150)
    private Integer age;

    @Schema(
        description = "ユーザーの役割",
        example = "USER",
        allowableValues = {"ADMIN", "USER", "GUEST"}
    )
    private String role;

    // getter/setter省略
}

@Schemaの主な属性は以下の通りです。

属性	説明
`description`	フィールドの説明
`example`	値の例
`requiredMode`	必須/任意の指定
`minLength` / `maxLength`	文字列長の制限
`minimum` / `maximum`	数値の範囲
`format`	値のフォーマット（email、date、uuidなど）
`allowableValues`	許容される値のリスト
`hidden`	ドキュメントから非表示にする

@Tagアノテーション

@Tagアノテーションは、コントローラ単位でAPIをグループ化し、説明を追加します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "Users", description = "ユーザー管理API")
@RestController
@RequestMapping("/api/users")
public class UserController {
    // エンドポイントの実装
}

@Tag(name = "Products", description = "商品管理API")
@RestController
@RequestMapping("/api/products")
public class ProductController {
    // エンドポイントの実装
}

レスポンスモデルの詳細定義

@Contentと@ExampleObjectの使用

レスポンスの具体的な形式と例を定義できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


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

@Operation(summary = "ユーザーを取得する")
@ApiResponses(value = {
    @ApiResponse(
        responseCode = "200",
        description = "ユーザーの取得に成功",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = UserResponse.class),
            examples = @ExampleObject(
                name = "成功例",
                value = """
                    {
                        "id": 1,
                        "name": "田中太郎",
                        "email": "tanaka@example.com",
                        "createdAt": "2026-01-04T10:00:00"
                    }
                    """
            )
        )
    ),
    @ApiResponse(
        responseCode = "404",
        description = "ユーザーが見つからない",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = ProblemDetail.class),
            examples = @ExampleObject(
                name = "エラー例",
                value = """
                    {
                        "type": "https://example.com/errors/user-not-found",
                        "title": "User Not Found",
                        "status": 404,
                        "detail": "指定されたIDのユーザーが見つかりません",
                        "instance": "/api/users/999"
                    }
                    """
            )
        )
    )
})
@GetMapping("/{id}")
public UserResponse getUser(@PathVariable Long id) {
    // 実装
}

API情報とセキュリティの設定

OpenAPIDefinitionによるグローバル設定

API全体の情報は@OpenAPIDefinitionアノテーションまたはBeanで設定します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.servers.Server;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "ユーザー管理API",
        version = "1.0.0",
        description = "ユーザーの登録・更新・削除を管理するREST API",
        contact = @Contact(
            name = "開発チーム",
            email = "dev-team@example.com",
            url = "https://example.com/support"
        ),
        license = @License(
            name = "Apache 2.0",
            url = "https://www.apache.org/licenses/LICENSE-2.0"
        )
    ),
    servers = {
        @Server(url = "http://localhost:8080", description = "開発環境"),
        @Server(url = "https://api.example.com", description = "本番環境")
    }
)
public class OpenApiConfig {
}

Beanによる設定

より柔軟な設定が必要な場合は、OpenAPIクラスのBeanを定義します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.List;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("ユーザー管理API")
                .version("1.0.0")
                .description("ユーザーの登録・更新・削除を管理するREST API")
                .contact(new Contact()
                    .name("開発チーム")
                    .email("dev-team@example.com"))
                .license(new License()
                    .name("Apache 2.0")
                    .url("https://www.apache.org/licenses/LICENSE-2.0")))
            .servers(List.of(
                new Server().url("http://localhost:8080").description("開発環境"),
                new Server().url("https://api.example.com").description("本番環境")
            ));
    }
}

セキュリティ設定（Bearer認証）

JWT認証などを使用するAPIでは、セキュリティスキームを設定します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT",
    description = "JWT認証トークン"
)
public class OpenApiSecurityConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info().title("セキュアAPI").version("1.0.0"))
            .addSecurityItem(new io.swagger.v3.oas.models.security.SecurityRequirement()
                .addList("bearerAuth"));
    }
}

コントローラで個別にセキュリティ要件を指定することもできます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


import io.swagger.v3.oas.annotations.security.SecurityRequirement;

@RestController
@RequestMapping("/api/admin")
@SecurityRequirement(name = "bearerAuth")
public class AdminController {

    @Operation(summary = "管理者専用エンドポイント")
    @GetMapping("/dashboard")
    public DashboardData getDashboard() {
        // 実装
    }
}

Swagger UIでのAPI動作確認

Swagger UIの基本操作

アプリケーションを起動し、ブラウザでhttp://localhost:8080/swagger-ui.htmlにアクセスすると、Swagger UIが表示されます。

Swagger UIでは以下の操作が可能です。

APIエンドポイントの閲覧: タグごとにグループ化されたエンドポイント一覧を確認できる
リクエストの実行: 「Try it out」ボタンでリアルタイムにAPIを呼び出せる
レスポンスの確認: 実際のレスポンスとHTTPステータスコードを確認できる
認証の設定: 「Authorize」ボタンで認証情報を設定できる

APIテストの実行手順

テストしたいエンドポイントをクリックして展開します
「Try it out」ボタンをクリックします
必要なパラメータやリクエストボディを入力します
「Execute」ボタンをクリックしてリクエストを送信します
下部に表示されるレスポンスを確認します

Swagger UIのカスタマイズ

application.propertiesまたはapplication.ymlでSwagger UIの動作をカスタマイズできます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


# Swagger UIのパスをカスタマイズ
springdoc:
  swagger-ui:
    path: /api-docs-ui
    # デフォルトで展開する操作
    doc-expansion: none
    # リクエストの実行時間を表示
    display-request-duration: true
    # 操作IDを表示
    display-operation-id: true
    # タグをアルファベット順にソート
    tags-sorter: alpha
    # 操作をアルファベット順にソート
    operations-sorter: alpha
    # 「Try it out」をデフォルトで有効化
    try-it-out-enabled: true
    # シンタックスハイライトのテーマ
    syntax-highlight:
      theme: monokai

OpenAPI仕様書のエクスポート

JSON/YAML形式での取得

SpringDoc OpenAPIは、OpenAPI仕様書を以下のエンドポイントで提供します。

1
2
3
4
5


# JSON形式
curl http://localhost:8080/v3/api-docs

# YAML形式
curl http://localhost:8080/v3/api-docs.yaml

ファイルへの保存

curlコマンドでファイルに保存できます。

1
2
3
4
5


# JSON形式で保存
curl -o openapi.json http://localhost:8080/v3/api-docs

# YAML形式で保存
curl -o openapi.yaml http://localhost:8080/v3/api-docs.yaml

ビルド時に仕様書を生成する

Mavenプラグインを使用して、ビルド時にOpenAPI仕様書を生成することもできます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.4</version>
    <executions>
        <execution>
            <id>generate-openapi</id>
            <phase>integration-test</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
        <outputFileName>openapi.json</outputFileName>
        <outputDir>${project.build.directory}</outputDir>
    </configuration>
</plugin>

OpenAPI Generatorとの連携

エクスポートしたOpenAPI仕様書は、OpenAPI Generatorを使用してクライアントSDKを生成できます。

1
2
3
4
5


# TypeScriptクライアントの生成
npx @openapitools/openapi-generator-cli generate \
    -i openapi.json \
    -g typescript-fetch \
    -o ./generated-client

環境別の設定とセキュリティ

本番環境でのSwagger UI無効化

本番環境ではセキュリティ上の理由からSwagger UIを無効化することが推奨されます。

1
2
3
4
5
6


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

または、プロファイルごとに依存関係を切り替える方法もあります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


<profiles>
    <profile>
        <id>dev</id>
        <dependencies>
            <dependency>
                <groupId>org.springdoc</groupId>
                <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
                <version>2.8.5</version>
            </dependency>
        </dependencies>
    </profile>
</profiles>

Spring Security環境での設定

Spring Securityを使用している場合、Swagger UIとAPIドキュメントへのアクセスを許可する設定が必要です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


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

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                // Swagger UIとOpenAPIドキュメントを許可
                .requestMatchers(
                    "/v3/api-docs/**",
                    "/v3/api-docs.yaml",
                    "/swagger-ui/**",
                    "/swagger-ui.html"
                ).permitAll()
                // その他のリクエストは認証必要
                .anyRequest().authenticated()
            );
        return http.build();
    }
}

エンドポイントのパスカスタマイズ

デフォルトのパスを変更したい場合は、以下の設定を使用します。

1
2
3
4
5


springdoc:
  api-docs:
    path: /api/v3/docs
  swagger-ui:
    path: /api/swagger-ui

実践的なユースケース

ページネーションレスポンスの定義

Spring DataのPageオブジェクトをドキュメント化する例です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


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

@Schema(description = "ページネーションレスポンス")
public class PageResponse<T> {

    @Schema(description = "コンテンツリスト")
    private List<T> content;

    @Schema(description = "現在のページ番号（0始まり）", example = "0")
    private int page;

    @Schema(description = "1ページあたりの件数", example = "20")
    private int size;

    @Schema(description = "総件数", example = "100")
    private long totalElements;

    @Schema(description = "総ページ数", example = "5")
    private int totalPages;

    @Schema(description = "最初のページかどうか", example = "true")
    private boolean first;

    @Schema(description = "最後のページかどうか", example = "false")
    private boolean last;

    // getter/setter省略
}

ファイルアップロードAPIの定義

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import org.springframework.http.MediaType;
import org.springframework.web.multipart.MultipartFile;

@RestController
@RequestMapping("/api/files")
@Tag(name = "Files", description = "ファイル管理API")
public class FileController {

    @Operation(summary = "ファイルをアップロードする")
    @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public FileUploadResponse uploadFile(
        @RequestBody(
            description = "アップロードするファイル",
            content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA_VALUE)
        )
        @RequestParam("file") MultipartFile file
    ) {
        // 実装
    }
}

特定のエンドポイントを非表示にする

内部用のエンドポイントをドキュメントから除外したい場合は、@Hiddenアノテーションを使用します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


import io.swagger.v3.oas.annotations.Hidden;

@RestController
@RequestMapping("/api/internal")
@Hidden  // このコントローラ全体を非表示
public class InternalController {
    // 内部用エンドポイント
}

// または個別のメソッドに適用
@Operation(hidden = true)
@GetMapping("/health-check")
public String healthCheck() {
    return "OK";
}

処理フローの可視化

SpringDoc OpenAPIを活用したAPI開発からドキュメント公開までの流れを以下に示します。

flowchart TD
    A[REST APIの実装] --> B[アノテーションの追加]
    B --> C[アプリケーション起動]
    C --> D{環境の判定}
    D -->|開発環境| E[Swagger UI有効]
    D -->|本番環境| F[Swagger UI無効]
    E --> G[Swagger UIでテスト]
    G --> H[OpenAPI仕様書エクスポート]
    H --> I[クライアントSDK生成]
    H --> J[外部ドキュメントツール連携]
    F --> K[APIドキュメントのみ提供]

まとめ

SpringDoc OpenAPIを使用することで、Spring Boot REST APIのドキュメント作成を大幅に効率化できます。本記事で紹介した内容をまとめると以下の通りです。

springdoc-openapi-starter-webmvc-ui依存関係の追加だけで、Swagger UIとOpenAPI仕様書生成が有効になる
@Operation、@Parameter、@Schemaアノテーションで詳細なAPI説明を追加できる
Swagger UIを使用して、ブラウザ上でAPIのテストと動作確認が可能
OpenAPI仕様書をJSON/YAML形式でエクスポートし、クライアントSDK生成や外部ツール連携に活用できる
本番環境ではセキュリティを考慮し、Swagger UIを無効化するべき

APIドキュメントをコードと同期させることで、ドキュメントの陳腐化を防ぎ、チーム開発の効率を向上させることができます。

実行環境と前提条件#

期待される学習成果#

OpenAPI仕様とSpringDoc OpenAPIの概要#

OpenAPI仕様とは#

SpringDoc OpenAPIとは#

SpringDoc OpenAPIの導入#

依存関係の追加#

WebFluxプロジェクトの場合#

動作確認#

アノテーションによるAPI説明の記述#

@Operationアノテーション#

@Parameterアノテーション#

@Schemaアノテーション#

@Tagアノテーション#

レスポンスモデルの詳細定義#

@Contentと@ExampleObjectの使用#

API情報とセキュリティの設定#

OpenAPIDefinitionによるグローバル設定#

Beanによる設定#

セキュリティ設定（Bearer認証）#

Swagger UIでのAPI動作確認#

Swagger UIの基本操作#

APIテストの実行手順#

Swagger UIのカスタマイズ#

OpenAPI仕様書のエクスポート#

JSON/YAML形式での取得#

ファイルへの保存#

ビルド時に仕様書を生成する#

OpenAPI Generatorとの連携#

環境別の設定とセキュリティ#

本番環境でのSwagger UI無効化#

Spring Security環境での設定#

エンドポイントのパスカスタマイズ#

実践的なユースケース#

ページネーションレスポンスの定義#

ファイルアップロードAPIの定義#

特定のエンドポイントを非表示にする#

処理フローの可視化#

まとめ#

参考リンク#