# 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) (필자의 스프링 3.2.4 환경의 경우 2.8.6 버전은 오류가 나왔으나 2.3.0 버전은 정상 작동 확인) ```Groovy implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0' ``` 의존성을 추가한 후 아래의 주소로 접속을 확인합니다. ``` 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) ); } } ```

만약 문서에서의 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) ); } } ```

Swagger UI 예시 - API 설명 추가 — 그림 4. API 설명 추가 예시

## 파라미터 설명 작성 각각의 파라미터의 앞에도 아래와 같이 설명을 추가할 수 있습니다. ```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. 랩퍼에 의한 반환값 예시

해당 문제를 해결하기 위해서는 크게 두 가지 방법이 있습니다. ## 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) ); } ```

Swagger UI 예시 - 내부 타입 명시 — 그림 7. 내부 타입 명시

## 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을 이용하여 생성 후 postman 문서의 링크를 추가하는 방식으로 이용 중입니다.

Swagger UI 예시 - Postman 링크 추가 — 그림 9. Postman 링크 추가

Kyumin.dev