🔥 Spring Boot 3.4 + springdoc-openapi 사용 시 발생한 NoSuchMethodError 해결기

최근 Spring Boot 3.4 프로젝트에서 Swagger(OpenAPI) 문서를 적용하기 위해 springdoc-openapi를 도입했는데, 예상치 못한 런타임 에러를 마주하게 됐습니다. 이 포스트에서는 해당 에러의 원인과 해결 방법을 공유합니다.

문제 상황

항목	설정
Spring Boot 버전	3.4.0
Java 버전	17
Swagger 라이브러리	springdoc-openapi 2.5.0

• API 문서 확인을 위해 /v3/api-docs 요청을 보냈을 때 발생

• IntelliJ에서는 컴파일 에러 없이 잘 실행되지만, Swagger 문서를 요청하는 순간 500 Internal Server Error 발생

원인 분석

❗ 문제의 핵심은 ControllerAdviceBean 생성자 불일치

Handler dispatch failed: java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean.(java.lang.Object)'

에러 로그를 확인해 봤을때 존재하지 않는 메서드를 호출해서 문제가 발생한것으로 보입니다.

-> 따라서 빈을 주입하며 초기화하는 과정에서 문제가 발생한것으로 판단하여 혹시 호환되는 버젼이 달라서 초기화를 하지 못하는가 의심되어 먼저 해당부분을 살펴 보았습니다.

springDoc 공식 문서에 가보면 각각 호환되는 버젼이 나와있습니다.

제가 프로젝트에 사용한것은 스프링부트 3,.4 버젼이지만 Springdoc OpenAPI 버젼은 2.5. 버젼을 사용하여 호환되지 않는 문제 였습니다.

어떤차이가 있을까??

버젼에 따라서 어떤 차이가 있을까 하고 구글링과 공식문서를 보고 판단한 것은 다음과 같습니다.

Springdoc OpenAPI 2.5. 버젼에 대응되는 스프링 부트의 버젼은 3.2(springFramework 6.1)

스프링 프레임워크 공식문서를 확인해보면 문제를 일으킨 ControllerAdviceBean의 생성자를 확인할수 있습니다.

ControllerAdviceBean(Object bean)
ControllerAdviceBean(String beanName, BeanFactory beanFactory)
ControllerAdviceBean(String beanName, BeanFactory beanFactory, ControllerAdvice controllerAdvice)

이렇게 3개의 생성자가 존재하는 것을 확인할수 있었습니다.

그렇다면 프로젝트에 사용중인 스프링 부트의 버젼은 3.4(springFramework 6.2)은 어떤 생성자를 가지고 있는지 확인해 보았습니다.

ControllerAdviceBean(String beanName, BeanFactory beanFactory, ControllerAdvice controllerAdvice)

위와같이 생성자를 하나만 가지고 있는것을 확인하였습니다.

결론

따라서 스프링 프레임워크의 버젼에 따라 생성자가 다르고 각각에 대응할수 있도록 Springdoc OpenAPI 도 버젼을 다르게 구현 되어있어 서로 호환되는 버젼인 2.7이상을 사용하여 해결 할수 있었습니다.

참고문서

• springDoc 공식문서 : https://springdoc.org/#what-is-the-compatibility-matrix-of-springdoc-openapi-with-spring-boot
• spring-framework 공식문서 (6.1버젼) : https://docs.spring.io/spring-framework/docs/6.1.21/javadoc-api/org/springframework/web/method/ControllerAdviceBean.html
• spring-framework 공식문서 (6.2버젼) :
  https://docs.spring.io/spring-framework/docs/6.2.8/javadoc-api/org/springframework/web/method/ControllerAdviceBean.html
• 관련된 stackoverflow 답변 : https://stackoverflow.com/questions/64473435/controlleradvice-does-not-allow-swagger-ui-to-be-displayed