머니톡 프로젝트 트러블슈팅 01 - SpringDoc과 GlobalExceptionHandler 충돌 이슈 해결기

문제 상황

springdoc-openapi-starter-webmvc-ui 의존성을 추가하고 @RestControllerAdvice 기반의 GlobalExceptionHandler를 만들었더니, 아래와 같은 NoSuchMethodError 발생:

java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)'

 

Swagger UI가 정상적으로 로딩되지 않고, 서버가 부팅 중에 에러가 발생함.

---

 

의미

springdoc-openapi 라이브러리가 org.springframework.web.method.ControllerAdviceBean 클래스의 특정 생성자(ControllerAdviceBean(Object))를 호출하려는데 실제로 그 메서드가 없음.

 

---

원인 분석

• springdoc-openapi-starter는 내부적으로 Spring의 ControllerAdviceBean을 사용.
• 이 클래스는 Spring Framework 6.1 이상에서 생성자 시그니처가 변경되었음.
• 반면, 내 프로젝트는 spring-boot 3.4.x를 사용 중이었고, 이는 Spring Framework 6.0.x 기반이므로 버전 불일치가 발생한 것.

---

해결 방법

1. Spring Boot 버전 다운그레이드

• 기존: 3.4.4 → 변경: 3.2.4 (→ 내부적으로 Spring Framework 6.1.x 사용)

plugins { id 'org.springframework.boot' version '3.2.4' }

2. Gradle 캐시 새로고침

./gradlew clean build --refresh-dependencies

3. 서버 재시작

./gradlew bootRun

 

---

최종 적용된 주요 의존성

implementation 'org.springframework.boot:spring-boot-starter-web' implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

---

 

🎉 결과

• Swagger UI 정상 동작
• GlobalExceptionHandler 작동
• JWT 보안 필터 + 인증 토큰 테스트도 Swagger에서 성공