Springboot3, Kotlin으로 백엔드 서버를 구성중인데, 이제 슬슬 프론트엔드와 붙이기 위해 Swagger UI를 적용해보기로 했다. 이 프로젝트 이전에는 FastAPI를 이용해서 작성을 했었던 자료인데, 같이 협업하시는 프론트 담당자분께서 Swagger 문서가 나오는걸 선호하시는 것 같아 테스트 겸 적용을 해보기로 했다.
springdoc-openapi 의존성 추가
Maven Repository로 가서 springdoc-openapi 검색 후 의존성을 추가했다.
implementation("org.springdoc:springdoc-openapi-ui:1.7.0")application.yaml 파일 수정
이후 application.yaml 파일에 springdoc 관련 설정을 추가하였다.
# application.yaml
springdoc:
swagger-ui:
path: /swagger-ui.html
disable-swagger-default-url: true
display-request-duration: true
operations-sorter: alpha
default-consumes-media-type: application/json;charset=UTF-8
default-produces-media-type: application/json;charset=UTF-8
packages-to-scan: com.myproject.controller
swagger 문서 path를 설정해주고, controller 자동 인식을 위해 packages-to-scan 설정을 추가하여 Springdoc이 스캔하면서 API 문서를 생성할 패키지를 지정하였다. 또한, operations-sorter: alpha 옵션으로 알파벳 순서대로 정렬할 수 있도록 하였다.
그리고 기본적 media-type을 명시적으로 지정해주지 않으면 디폴트값으로 application/json 타입인데, charset=UTF-8 설정을 추가해주었다.
🤦♀️ 빌드 실패
이후 빌드를 했더니 아래와 같은 에러가 발생했다.
Failed to introspect Class [org.springdoc.webmvc.api.OpenApiWebMvcResource] from ClassLoader [jdk.internal.loader.ClassLoaders$AppClassLoader@4e0e2f2a]
왜일까 확인해보니, spring-boot v3는 springdoc-openapi v2를 사용해야 한다고 나와있다.
그래서 아래와 같은 의존성을 추가해줬다.
// build.gradle.kts
implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0")그런데도 동일한 에러가 발생했다. 내가 springdoc-openapi-ui와 springdoc-openapi-starter-webmvc-ui 두 개의 의존성을 모두 추가했었는데, 에러가 난 이유는 내가 두 개의 의존성을 함께 사용해서 이 모듈들의 충돌문제인 것 같았다.
😇 해결
💡 Springdoc 의존성을 하나만 사용한다
나는 무조건 springdoc-openapi-ui가 무조건 들어가야 한다고 생각했다. 하지만, springdoc-openapi 의존성은 하나만 추가해주면 된다.
그래서 나는 springboot3.X 버전을 사용하고 있으므로 springdoc-openapi v2 버전을 사용하기 위해 springdoc-openapi-ui 의존성을 삭제하고 springdoc-openapi-starter-webmvc-ui만 사용하였다.
참고로, springdoc-openapi-starter-webmvc-ui는 springdoc-openapi-ui의 기능에 몇 가지 편의성 설정이 추가된 패키지이다. springdoc-openapi-ui가 Spring MVC와 Spring WebFlux 모두에서 사용되는 기본 모듈로 좀 더 범용적으로 사용되지만 v2 사용을 위해 springdoc-openapi-starter-webmvc-ui로 추가해줬더니 문제 없이 빌드되면서 swagger 페이지가 뜨는 것을 확인했다.
