Swagger failed to load api definition 오류

❎ 문제발생

로그아웃 기능을 추가하기 위해서 작업을 하던중 테스트를 위해서 스웨거에 접속하니 오류가 발생하였다.

평소에 제대로 작동하던 스웨거가 갑자기 오류가 발생하면서 접속이 안되는 상황이다.

 

 

🆘 해결 과정

기본적으로 서버측에는 어떤 로그도 나와있지 않는 상황이다.

기존까지 되던것이 기능을 추가하고 동작하지 않으니 해당 기능이 문제라고 판단하여 추가한 코드를 주석처리를 해도 여전히 스웨거 접속이 불가능하였다.

ChatGpt의 도움도 빌려보았으나 해결이 되지 않았고 계속해서 구글링을 해본 결과 전역적으로 예외처리를 하는 부분에서 문제가 있다는 블로그를 발견하였다.

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 

[해커톤] HY-THON 트러블슈팅 - Swagger 500 에러: Failed to load API definition

 

마찬가지로 똑같이 @ControllerAdvice 부분을 주석처리 하였더니 정상적으로 작동하였다.

package hjp.hjchat.infra.security

import hjp.hjchat.infra.security.exception.DuplicateEmailException
import hjp.hjchat.infra.security.exception.DuplicateUsernameException
import hjp.hjchat.infra.security.exception.PasswordMismatchException
import org.springframework.web.bind.annotation.ControllerAdvice
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.http.ResponseEntity
import org.springframework.http.HttpStatus
import jakarta.servlet.http.HttpServletRequest

//@ControllerAdvice
class GlobalExceptionHandler {

    @ExceptionHandler(DuplicateUsernameException::class)
    fun handleDuplicateUsernameException(ex: DuplicateUsernameException): ResponseEntity<ErrorResponse> {
        return ResponseEntity(
            ErrorResponse(message = ex.message ?: "중복된 사용자 이름이 존재합니다."),
            HttpStatus.BAD_REQUEST // 400 상태 코드
        )
    }

    @ExceptionHandler(DuplicateEmailException::class)
    fun handleDuplicateEmailException(ex: DuplicateEmailException): ResponseEntity<ErrorResponse> {
        return ResponseEntity(
            ErrorResponse(message = ex.message ?: "중복된 이메일이 존재합니다."),
            HttpStatus.BAD_REQUEST
        )
    }

    @ExceptionHandler(PasswordMismatchException::class)
    fun handlePasswordMismatchException(ex: PasswordMismatchException): ResponseEntity<ErrorResponse> {
        return ResponseEntity(
            ErrorResponse(message = ex.message ?: "비밀번호와 확인 비밀번호가 일치하지 않습니다."),
            HttpStatus.BAD_REQUEST
        )
    }




    @ExceptionHandler(Exception::class)
    fun handleGenericException(request: HttpServletRequest, ex: Exception): ResponseEntity<ErrorResponse> {
        // Swagger 관련 경로 제외
        if (request.requestURI.contains("/v3/api-docs") || request.requestURI.contains("/swagger-ui")) {
            // Swagger 경로는 예외 처리에서 제외합니다.
            return ResponseEntity(
                ErrorResponse(message = "Swagger 요청 중 오류가 발생했습니다."),
                HttpStatus.INTERNAL_SERVER_ERROR
            )
        }

        // 다른 경로에 대한 예외 처리
        return ResponseEntity(
            ErrorResponse(message = "서버에서 처리 중 오류가 발생했습니다."),
            HttpStatus.INTERNAL_SERVER_ERROR
        )
    }

    data class ErrorResponse(
        val message: String
    )
}

@ControllerAdvice를 주석처리 한 상황

전역처리 하는 부분의 코드를 수정해보았다.

이전 코드

if (request.requestURI.contains("/v3/api-docs") || request.requestURI.contains("/swagger-ui")) {
    return ResponseEntity(
        ErrorResponse(message = "Swagger 요청 중 오류가 발생했습니다."),
        HttpStatus.INTERNAL_SERVER_ERROR
    )
}

 

수정된 코드

if (request.requestURI.contains("/v3/api-docs") || request.requestURI.contains("/swagger-ui")) {
    return ResponseEntity.ok().build()
}

스웨거 접속은 되지만 api명세서를 제공받지 못하는 상황이다.

 

 

✔ 해결

문제의 원인: @ControllerAdvice는  Spring MVC 전역 예외처리를  담당하는 어노테이션이기 때문에 프로젝트 전체에서 발생하는 예외처리를 한곳에서 처리할수 있게 하기 때문에 예외처리가 발생하면 Swagger에도 영향을 미친것이다.

Swagger는 테스트단계에서만 사용할것이기 때문에 Swagger로 테스트를 할때만 @ControllerAdvice를 주석처리 하는것으로 해결하였다.