[SpringBoot] @RestControllerAdvice와 Swagger 충돌

 

❌사건의 발단

⚙️환경
- SpringBoot 4.3.2
- Swagger: org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2

 

개발을 하다가 API마다 예외 처리 코드를 작성하는 게 너무 귀찮고 시간이 많이 들기도 해서 어떻게 방법이 없나 고민하던 찰나에, `@RestControllerAdvice` 어노테이션을 스프링부트에서 제공한단 사실을 알게 되었습니다.

 

예외처리 핸들러 클래스를 지정하여 해당 어노테이션을 붙이면, 지정한 패키지 경로에 있는 클래스들에서 던진 예외를 받아서 처리할 수 있더라구요. 이렇게 전역적인 핸들러 클래스를 지정하니, `Controller`에서 `try-catch`를 쓸 필요가 없었습니다. 😊

 

근데 문제는 `@RestControllerAdvice`를 적용하고 나니까 Swagger가 접속이 안 됐습니다.

"Failed to load API Definition"
"Fetch Errors - response status is 403. /v3/api-docs"

 

찾아보니까 SpringDoc(Swagger)은 API 문서를 자동으로 생성하기 위해, 모든 컨트롤러와 관련된 클래스들을 스캔한다고 합니다. 그런데 @RestControllerAdvice는 전역적으로 예외를 처리하는 특별한 컨트롤러이므로, SpringDoc이 이를 일반 컨트롤러처럼 문서화하려고 시도하면서 충돌이 발생하는 것 같아요.

 

✅해결 방법

1. `@Hidden` 어노테이션을 붙여, SpringDoc에게 이 클래스는 문서화하지 말라고 명시하기

@RestControllerAdvice(basePackages = "domain.controller.auth")
@Slf4j
@Order(Ordered.HIGHEST_PRECEDENCE)
@Hidden  // Swagger 문서에서 이 클래스 제외
public class AuthExceptionHandler {
	...
}

 

저는 이 방법으로 해결했습니다.

 

2. SwaggerConfig에서 @RestControllerAdvice가 있는 경로를 제외하고 문서 생성