TIL - 2/27

• 팀 프로젝트에서 Swagger를 도입하기 위해 구현하는 도중 발생한 문제이다.

Error

스웨거의 URL 인 /swagger 를 접속했는데, Fail To load API 문구가 떴다.....
스웨거에 대해선 직접 구현해본 경험이 없어서 몸으로 부딪히다가 난 에러라 좀 당황스러웠다.
(FastAPI 가 좋은거구나...)

해결은?

에러를 찾아보니 @RestControllerAdvice 를 쓰지않았을 때
동작이 되는 블로그 글을 찾아본 후 직접 적용해봤는데 똑같은 에러였다.

그럼 왜 생겼을까?

@ControllerAdvice 애노테이션과 Swagger 사이에 일어난 충돌이다.

@ControllerAdvice가 없다면 Swagger는 controller class를 가져와 API 정의를 분석한다.
@ControllerAdvice가 있다면 Swagger 응답이 내가 응답을 통일해 둔 방식으로 변환되고, 
Swagger 웹 페이지는 응답 구조를 인식할 수 없게 된다.

해결

• 블로그 저자분께서는 @RestControllerAdvice 어노테이션을 통해 annotations 와 backPakages 를 사용하여 해결했지만, 자바 플러그인의 버전을 명시적으로 낮췄다.

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

• 해결하기 위한 방법이 여러가지이지만, 해결에 대한 방법이 꼭 한가지 방법만 고집할 필요는 없다고 생각한다.
  왜 이런 오류가 났는지는 중요하지만....!
  나에겐 스웨거의 단점이 더 많이 보인 탓에 선호하는 툴은 아니지만 그래도 사용해본 경험이 중요하다고 느낀 하루였다.

출처: https://dev-meung.tistory.com/entry/해커톤-HY-THON-트러블슈팅-Swagger-500-에러-Failed-to-load-API-definition
[IT::Coding:티스토리]