20241216 TIL : Swagger java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean 에러 발생 및 접속되지 않는 오류(500 Internal Server Error)

오늘 학습한 내용

• Swagger 500 Internal Server Error
  • 에러 발생 원인
  • 해결 과정
  • 참고 자료

Swagger 500 Internal Server Error

Swagger를 추가하던 중 다음과 같은 에러가 발생했다.

2024-12-16T16:07:18.302+09:00 ERROR 12804 --- [user-service] [io-19092-exec-9] [] o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Handler dispatch failed: java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)'] with root cause
java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)'
...

java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean 에러가 발생했는데, 처음 보는 에러라 당황했다. 일단 에러 내용으로 봤을 때, ControllerAdvice에서 에러가 났을 가능성이 높아 보였다.

에러 발생 원인

정확한 원인은 알아내지 못했지만, ControllerAdvice 관련 에러라면 이것을 사용하는 곳이 딱 하나 있었다.

@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler({IllegalArgumentException.class})
    public ResponseEntity<RestApiException> illegalArgumentException(final IllegalArgumentException ex) {

        log.warn("IllegalArgumentException 발생: {}", ex.getMessage());

        RestApiException restApiException = RestApiException.builder()
                .errorMessage(ex.getMessage())
                .build();

        return new ResponseEntity<>(
                restApiException,
                HttpStatus.BAD_REQUEST
        );
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<RestApiException> handleValidationExceptions(MethodArgumentNotValidException ex) {

        log.warn("handleValidationExceptions 발생: {}", ex.getMessage());

        StringBuilder errorMessages = new StringBuilder();

        ex.getBindingResult().getFieldErrors().forEach(error ->
                errorMessages.append(error.getField())
                        .append(" : ")
                        .append(error.getDefaultMessage())
                        .append(" ")
        );

        RestApiException restApiException = RestApiException.builder()
                .errorMessage(errorMessages.toString())
                .build();

        return new ResponseEntity<>(
                restApiException,
                HttpStatus.BAD_REQUEST
        );
    }
}

여기서 @RestControllerAdvice 어노테이션을 사용하고 있다. 그래서 어노테이션을 주석처리 해 보았더니, 정상적으로 swagger에 접속이 되는 것을 확인했다.

해결 과정

@RestControllerAdvice(basePackages = {"com.sparta.user.domain.controller"})

어노테이션에 basePackages를 추가한다.
이후 의존성을 수정해보았다.

// swagger
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'

기존에 2.3.0, 2,6,0 버전으로 시도해보았는데, 가장 최신 버전인 2.7.0 버전으로 올려보았더니 해결되었다.

basePackages 관련 내용은 구글링을 통해 찾아서 시도해보았으나 해결되지 않았었고, 버전을 올렸더니 해결되었다니 굉장히 허무했다...

참고 자료

https://dev-meung.tistory.com/entry/%ED%95%B4%EC%BB%A4%ED%86%A4-HY-THON-%ED%8A%B8%EB%9F%AC%EB%B8%94%EC%8A%88%ED%8C%85-Swagger-500-%EC%97%90%EB%9F%AC-Failed-to-load-API-definition#%ED%95%B4%EA%B2%B0%EB%B0%A9%EC%95%883-1