개요
작년 말 운영하고 있던 프로젝트에서 Spring Boot 버전을 2.6.x 버전으로 올리면서
기존 SpringFox 라이브러리가 호환되지 않아 업데이트가 지속적으로 이루어지는 OAS3(OpenAPI Spec 3)를 사용하는 SpringDoc 으로 마이그레이션한 내용에 대해 공유
호환성 이슈 참고 링크
https://stackoverflow.com/questions/70178343/springfox-3-0-0-is-not-working-with-spring-boot-2-6-0
마이그레이션 방법
SpringFox > SpringDoc 마이그레이션 방법 문서
SpringDoc이 불친절한 것인지 커스텀 사용성을 더 넓혀준 것인지 모르겠으나
기존에 사용하던 SpringFox의 기본 Default 옵션들과 SpringDoc의 옵션은 차이가 크게 났었다.
아래와 같은 옵션을 주어야 그나마 기존에 사용하던 SpringFox의 옵션을 따라갈 수 있었다.
- 메서드 정렬, 태그 정렬, pre loading, request duration, ...
그 밖에 SwaggerConfig에도 일부 변경이 있었다.
변경된 Properties 관련 내용은 아래 링크에서 자세히 확인 가능하다.
주요 변경점
SpringDoc으로 변경되면서 기존 SpringFox에서 사용하던 @ApiModelProperty 의 역할과 @ApiModel 의 역할을 @Schema 가 수행하게 되었다.
이 때문에 Get 방식과 Post, Put, Delete, ... 방식의 Request Dto를 제공할때 스웨거 문서에 정상적으로 description이 스웨거 문서에 노출되지 않는 이슈가 발생하였다.
마이그레이션 진행 시 트러블 슈팅
기존 버전 PageableRq
기존 SpringFox에서는 잘 나오던 친구인데 SpringDoc에서는 아래처럼 Json형태로 나온다.
추가로, description 또한 확인 할 수 없다.
다음과 같이 사용해야 정상적으로 동작한다.
API를 Get 방식 메서드의 Rq 방식으로 제공할 때 QueryParam 으로 제공하게 되는데 이를 @ParameterObject 라는 어노테이션으로 스프링에 명시 해주어야 동작한다!
적용 결과
그런데, 여기에 한가지 문제가 더 있다.
기존 SpringFox는 @ApiModelProperty 하나로 description이 표기 되었지만 SpringDoc은 page, size, ... 등 @Schema 에 표기된 description이 표기되고 있지 않다.
이 부분도 아래와 같이 설정해주어야 정상적으로 사용자에게 표기된다.
적용 결과
정리하면 아래와 같다.
GET 메서드 사용시, QueryParam로 표기할 때는 @Parameter 어노테이션으로 지정
그외 POST, PUT, ... 사용시 RequestBody로 표기할 때는 @Schema 어노테이션으로 지정해야 정상적으로 동작한다.
번외
GET 메서드 & QueryParam 사용시, DTO 형태로 감싸지 않는 경우는 그냥 아래처럼 쓰면 OK
@Parameter(description = "검색 키워드") @RequestParam(required = false) String keyword