swagger 500 에러 해결

💡 https://github.com/cjh0412/Schedule

일정관리 API를 구현 후 테스트를 위해 swagger에 접속하던 중 콘솔 오류와 함께 아래와 같은 화면이 나타났다.

IntelliJ

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

원인 및 해결방법

NoSuchMethodError를 검색해보면 주로 메서드명을 찾지 못할때 나타난다고 한다.
하지만 나의 경우에는 swagger를 사용하지 않으면 오류 없이 정상동작 되었기 때문에 메서드 명 오류는 아니라고 생각했다.

💡 1차 시도

처음에는 swagger와 spring부트의 버전 차이로 인한 충돌로 생각됐기 때문에 swagger의 버전을 업그레이드 했다.

✅ build.gradle

수정 전

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

수정 후

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

1차 시도는 별다른 성과 없이 실패했다.

💡 2차 시도

예외처리부분을 작성 후부터 swagger가 정상 동작하지 않았기때문에 해당 부분의 여러 어노테이션을 주석처리한뒤 테스트 해본 결과@RestControllerAdvice를 주석처리하면 정상동작을 한다는 것을 알 수 있었다.

// @RestControllerAdvice swagger 오류로 인한 주석 처리
public class ExceptionController {

    @ExceptionHandler({ScheduleException.class})
    public ResponseEntity<?> handleScheduleException(final ScheduleException e){
        return ResponseEntity.badRequest().body(new ExceptionResponse(e.getMessage(), e.getErrorCode()));
    }

❗ 해결방안의 문제

@RestControllerAdvice을 주석처리한 경우

위와 같이 코드를 작성하면 swagger는 정상 동작하지만 예외가 발생한 경우 정확한 내용이 아래와 같이 확인되지 않는다는 단점이 존재하여 다른 방법을 찾아야했다.

💡 3차 시도

이전에 다른 프로젝트를 진행할 때는 이와 같은 오류가 발생하지 않았기 때문에 해당 프로젝트의 버전을 확인해본 결과 springBoot 버전이 3.3.1로 현재 3.4.1인 일정관리 프로젝트보다 낮다는 것을 알게 되었다.

그래서 springBoot 버전을 다운그레이드 한 뒤 재시도해본 결과 swagger가 정상 동작한다는 것을 확인했다.

✅ build.gradle

// 기존
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.4.1'
    id 'io.spring.dependency-management' version '1.1.7'
}
    }
    
// 수정
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.1'
    id 'io.spring.dependency-management' version '1.1.7'
}
    }    

❗ 해결방안의 문제

현재 내가 진행한 프로젝트는 개인프로젝트이므로 버전을 수정할 수 있었지만 만약 회사에서 진행하는 프로젝트라면? 기존에 사용하던 라이브러리와의 호환성 문제, 보안 문제 등 다양한 문제를 일으킬 수 있기 때문에 굉장히 위험한 해결방안이다. 때문에 새로운 방법을 찾아야했다.

💡 4차 시도

이것 저것 시도해봤지만 마땅한 해결법을 찾지 못하고 있을때 부트캠프를 진행하는 팀원분께 힌트를 얻어 해결하게 되었다.
그분이 주신 힌트는 application.properties에 속성을 추가하라는것!

✅ application.properties

// openApi 문서 활성화
springdoc.api-docs.enabled=true
// ui 활성화
springdoc.swagger-ui.enabled=true 
// 기본 접속 경로 지정
springdoc.swagger-ui.path=/swagger-ui.html 
// 일반화된 응답 사용 여부 결정
springdoc.override-with-generic-response=false 

이중 springdoc.override-with-generic-response=false가 오류 해결의 핵심이었던 것이다!
해당 내용을 살펴보면 false인 경우 응답이 자동으로 변환하지 않도록 제한하기 때문에 충돌을 방지한다

다음에 이와 같은 오류가 발생한다면 properties 속성 추가 가능 여부를 살펴봐야겠다.

기억해둘것!

📌 @RestControllerAdvice, @ControllerAdvice란?

• 공통점 : 여러 컨트롤러에서 발생하는 예외를 공통적으로 처리하기 위한 어노테이션
• 차이점
  • @RestControllerAdvice : @RestController에만 적용, @ResponseBody가 포함, API응답을 처리할 때 사용
  • @ControllerAdvice : @Controller, @RestController 모두 적용, @ResponseBody가 필요, view, JSON으로 반환 가능