[Swagger] Spring Boot 3.0.X 버전에서 Swagger UI 접속 시 404 에러가 발생할 때

목차

문제의 배경

JPA 공부를 위해 스프링부트 프로젝트를 생성할 때 새로운 버전을 사용해보자는 마음으로 스프링부트 3.0.3 버전으로 프로젝트를 생성했다. 그리고 평소처럼 Springdoc의 스웨거 UI를 사용해서 API를 호출하려고 했는데 스웨거 문서에 접속하니까 404 에러가 반겨줬다.

 

스웨거 API 문서에 접속하니까 찾을 수가 없다고 한다

그래들에 의존성은 기존처럼 implementation 'org.springdoc:springdoc-openapi-ui:1.6.11'를 추가해놨고, 아래와 같이 SwaggerConfig도 설정해놨고 애플리케이션 설정도 잡아놨는데 404 에러가 떠서 무엇이 문제인지 도저히 감을 잡지 못하고 있었다.

문제 해결

물론 JUnit5로 테스트를 하면 JPA를 테스트 해보는 것에 문제는 없지만, 실제로 API를 호출해보면서 JPA를 공부해보고 싶었기 때문에 스웨거를 사용하기 위해 구글링을 열심히 해보다가 답을 찾았다.

 

https://stackoverflow.com/questions/74614369/how-to-run-swagger-3-on-spring-boot-3

 

결론부터 이야기 하자면 스프링부트 3버전에서 Springdoc을 사용하기 위해서 Gradle / Maven에 추가해야하는 의존성이 이전과는 다르다는 점이다. Springdoc 공식 가이드 문서를 확인해보니 아예 Important라면서 v2를 사용하라는 안내가 있었다.

안내에 따라 v2 가이드 문서로 이동하니 추가하라고 하는 의존성 라이브러리가 다른 것을 확인할 수 있었다.

Springdoc v1

Springdoc v2

 

따라서 사용하는 빌드 툴에 따라 build.gradle 또는 pom.xml에 기존의 springdoc-openapi-ui가 아닌 아래의 의존성 라이브러리를 추가해주면 된다.

 

Gradle

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

Maven

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

 

 

의존성 라이브러리를 변경하니 기존과 같이 잘 접속되는 것을 볼 수 있다!

결론

결론은 스프링부트 버전에 따라 스웨거 UI를 사용하기 위해 추가해야 하는 Springdoc 라이브러리가 다르다. 스프링부트 3버전 이전에는 springdoc-openapi-ui를 추가해야, 스프링부트 3버전 이후에는 springdoc-openapi-starter-webmvc-ui를 추가해야 정상적으로 스웨거 UI를 사용할 수 있다. 만약 스프링부트 3버전에 springdoc-openapi-ui를 추가하면 그냥 스웨거 UI에만 접속되지 않을 뿐이고 애플리케이션 자체는 동작하지만, 스프링부트 3 이전 버전(2.7.x 등)에 springdoc-openapi-starter-webmvc-ui를 추가하게 되면 무수한 오류를 내뿜으며 애플리케이션이 바로 종료되어 버린다.

자바 17 이전의 버전을 사용한다면 버전이 맞지 않는다는 오류가 발생한다.

자바 17 이후의 버전을 사용한다면 UnsatisfiedDependencyException이 발생한다.

 

따라서, Springdoc의 스웨거 UI를 사용하려면 현재 프로젝트에서 사용하는 스프링부트 버전에 맞는 의존성 라이브러리를 추가해야 문제없이 사용할 수 있다.

참조 링크

Springboot 3.x에 Swagger를 적용시켜보자!

How to run Swagger 3 on Spring Boot 3

springdoc-openapi v2.0.2