# Spring Doc とは？ SpringDoc は、 Spring Boot プロジェクトにおいて OpenAPI 3.0 仕様に基づき、Swagger UI を通じて API ドキュメントを**自動生成**するライブラリです。従来の[Springfox](https://github.com/springfox/springfox)のメンテナンスが終了したため(最終更新: 2020 年)代替として近年多く使用されています。 --- # 環境構築 ## インストール以下のライブラリを、環境に適したバージョンでインストールします。 > [https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui](https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui) (筆者の Spring 3.2.4 環境では、2.8.6 バージョンでエラーが発生しましたが、2.3.0 バージョンでは正常に動作しました) ```Groovy implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0' ``` 依存関係を追加後、以下の URL にアクセスして確認します。 ``` http://localhost:[ポート番号]/swagger-ui/index.html ```

{" "} Spring Securityを使用している場合、以下のアドレスへのアクセスを許可する必要があります。 {"\n"} `.requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()` ## 基本設定接続に成功した場合、config 設定を通じてドキュメントの内容を追加します。 ```java @Configuration public class OpenApiConfig { @Bean public OpenAPI openAPI() { return new OpenAPI() .info(new Info() .title("Bannote API") .description("Bannote 백엔드 API 문서") .version("v1.0.0") .contact(new Contact() .name("Bannote Team") .url("https://github.com/Bannote") .email("kyumin12271227@gmail.com")) .license(new License() .name("MIT License") .url("https://opensource.org/licenses/MIT"))); } } ```

Swagger UI 例 - config設定 — 図2. Configを利用したドキュメント内容の修正

resources の application.yml または application.properties に以下のプロパティを追加します（任意）。 ```yaml springdoc: # Swagger UIの基本パス swagger-ui: path: /swagger-ui.html enabled: true operationsSorter: method tagsSorter: alpha # タグをアルファベット順にソート tryItOutEnabled: true filter: true # APIドキュメントのパス api-docs: path: /v3/api-docs enabled: true # スキャン対象のパッケージ設定 packages-to-scan: com.example.{パッケージの名} # マッチさせるパスの設定 paths-to-match: /** # セキュリティ関連の設定 show-login-endpoint: true enable-spring-security: true # キャッシュ無効化（開発環境に便利） cache: disabled: true ``` 詳細なプロパティ設定については、以下のドキュメントをご参照ください。 > [https://springdoc.org/properties.html](https://springdoc.org/properties.html) --- # 説明の記述 ## API の説明の記述例えば、以下のように RankingController に API がある場合、ドキュメントには以下のように表示されます。 ```java @RestController @RequestMapping("/api/ranking") @RequiredArgsConstructor public class RankingController { private final RankingApplicationService rankingApplicationService; @GetMapping("") public ResponseEntity getRanking( @RequestParam RankingType rankingType, @RequestParam PeriodType periodType, @RequestParam LocalDate startDate ) { ... return ResponseEntity.status(HttpStatus.OK).body( new ApiResult(true, "ランキング取得成功", ranking) ); } } ```

Swagger UI 例 - 基本ドキュメント — 図3. 基本APIドキュメント

API 名の変更や説明を追加したい場合、Tag と Operation を追加して以下のように記述できます。 ```java @Tag(name = "Fingerprint - ranking", description = "랭킹 API / ランキングAPI") @RestController @RequestMapping("/api/ranking") @RequiredArgsConstructor public class RankingController { private final RankingApplicationService rankingApplicationService; @Operation(summary = "랭킹 조회 / ランキング", description = "랭킹 타입, 기간타입, 시작일를 이용한 랭킹을 조회합니다. / ランキングタイプ、期間タイプ、開始日を使用してランキングを取得します。") @GetMapping("") public ResponseEntity getRanking( @RequestParam RankingType rankingType, @RequestParam PeriodType periodType, @RequestParam LocalDate startDate ) { ... return ResponseEntity.status(HttpStatus.OK).body( new ApiResult(true, "ランキング取得成功", ranking) ); } } ```

## パラメータの説明の記述各パラメータの前に以下のように説明を追加できます。 ```java @Parameter( description = "날짜 / 日付 (YYYY-MM-DD)", schema = @Schema(implementation = LocalDate.class), required = true) @RequestParam LocalDate startDate ```

Swagger UI 例 - パラメータ説明追加 — 図5. パラメータに説明を追加

# 制限事項 ## レスポンスラッパーを使用する場合レスポンスラッパーを使用する場合、以下のようにラッパーの型は表示されますが、内部の data の型が表示されない問題が発生します。 ```java @Getter @Setter @AllArgsConstructor public class ApiResult { private boolean success; private String message; private Object data; } ```

Swagger UI 例 - ラッパーによるレスポンス例 — 図6. ラッパーによるレスポンス例

この問題を解決するためには、主に 2 つの方法があります。 ## 1. 内部型の明示 ApiResponse に Schema を使用して、内部 data に含まれるクラスを明示します。 ```java @Operation(summary = "랭킹 조회 / ランキング", description = "랭킹 타입, 기간타입, 시작일를 이용한 랭킹을 조회합니다. / ランキングタイプ、期間タイプ、開始日を使用してランキングを取得します。") @GetMapping("") @ApiResponse(responseCode = "200", description = "랭킹 조회 성공 / ランキング取得成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = RankingResponseDto.class) )) public ResponseEntity getRanking( @RequestParam RankingType rankingType, @RequestParam PeriodType periodType, @RequestParam LocalDate startDate) { ... return ResponseEntity.status(HttpStatus.OK).body( new ApiResult(true, "ランキング取得成功", ranking) ); } ```

## 2. レスポンス例の追加 ApiResponse に example を使用して、レスポンスの例を追加することも可能です。 ```java @Operation(summary = "랭킹 조회 / ランキング", description = "랭킹 타입, 기간타입, 시작일를 이용한 랭킹을 조회합니다. / ランキングタイプ、期間タイプ、開始日を使用してランキングを取得します。") @GetMapping("") @ApiResponse(responseCode = "200", description = "랭킹 조회 성공 / ランキング取得成功", content = @Content(mediaType = "application/json", examples = @ExampleObject(value = """ { "success": true, "message": "랭킹 조회 성공", "data": { "rankingType": "체류_시간", "periodType": "월간", "startDate": "2025-04-01", "rankList": [ { "studentNumber": "24230XX", "givenName": "XX", "familyName": "X", "profileImageUrl": null, "rank": 1, "formattedValue": "347시간58분", "attendCount": 0 }, { "studentNumber": "24230XX", "givenName": "XX", "familyName": "X", "profileImageUrl": "images/profile/24230XX/example.gif", "rank": 2, "formattedValue": "335시간51분", "attendCount": 0 }, ... ] } } """))) public ResponseEntity getRanking( @RequestParam RankingType rankingType, @RequestParam PeriodType periodType, @RequestParam LocalDate startDate) { ... return ResponseEntity.status(HttpStatus.OK).body( new ApiResult(true, "ランキング取得成功", ranking) ); } ```

Swagger UI 例 - レスポンス例の追加 — 図8. レスポンス例の追加

# 結論レスポンスラッパー内部のデータ構造を明示するために複数の方法を試みましたが、内部型を明示する方法では逆にラッパーの型が表示されず、正確なレスポンス構造が伝わらないという課題がありました。また、レスポンス例をコードに直接埋め込む方法では、開発工数が多く、コードの可読性が低下するというデメリットもありました。そのため現在は、API の説明やパラメータの説明には Spring Doc を使用し、レスポンスの具体例は Postman を利用して作成したドキュメントをリンクで共有する方式を採用しています。

Swagger UI 例 - Postmanリンク追加 — 図9. Postmanリンクの追加

Kyumin.dev