refactor : @ControllerAdvice와 Swagger UI 충돌로 인한 오류

[hye-inA]

📌 Description ( 작업 상세 내용 )

환경

• Spring Boot: 3.4.8 (Java 21)
• springdoc-openapi: 2.6.0 (springdoc-openapi-starter-webmvc-ui)

설명

• 전역 예외 처리로 @ControllerAdvice(+ @responsebody)를 설정한 상태에서 Swagger UI 접속 시"Failed to load API definition" 오류와 함께 500 에러를 발생
• 오류 로그

Resolved [jakarta.servlet.ServletException: Handler dispatch failed: 
java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)']

원인 분석

Spring Framework/Spring Boot 버전과 Swagger(OpenAPI) 라이브러리 버전 간의 호환성 불일치

Spring Boot 3.4.x(= Spring Framework 6.2.x)에서 ControllerAdviceBean 생성자 시그니처가 바뀌었고,
springdoc-openapi 2.6.0이 해당 변경과 호환되지 않아 NoSuchMethodError가 발생한 것으로 보임

해결 방안

1. springdoc-openapi 버전 업그레이드 : Spring Boot 3.4 (Spring Framework 6.2)와 호환되는 Springdoc OpenAPI 버전은 2.7.0 이상이므로 2.7.0 버전으로 올리기
2. ControllerAdvice 범위 제한 : @ControllerAdvice(basePackages = "…")와 같이 basePackages 속성을 지정해 적용 범위를 특정 패키지로 한정

참고 자료

https://stackoverflow.com/questions/64473435/controlleradvice-does-not-allow-swagger-ui-to-be-displayed#:~:text=1