3일차 Spring Boot + Swagger 적용 (버전 이슈 문제 발생, 해결), Exception 분리

오늘은 드디어 내가 만든 API들을 Swagger로 문서화하고 직접 테스트할 수 있도록 적용해봤다.

---

✅ 오늘 목표

• 예외 처리를 위한 GlobalExceptionHandler 적용
• Swagger(OpenAPI 3)를 프로젝트에 적용해서 API 문서 자동화
• Postman 없이 API 테스트 가능하게 만들기

---

🚨 예외 처리 GlobalExceptionHandler로 분리

POST 요청 시 유효성 검사가 실패할 경우, 기본 에러 메시지는 너무 복잡하게 나온다.
그래서 직접 예외처리 클래스를 만들어서 다음처럼 정리된 메시지를 내려주도록 만들었다.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<?> handleValidationErrors(MethodArgumentNotValidException ex) {
        List<String> errors = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(err -> err.getDefaultMessage())
            .collect(Collectors.toList());

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

    static class ErrorResponse {
        public List<String> errors;

        public ErrorResponse(List<String> errors) {
            this.errors = errors;
        }

        public List<String> getErrors() {
            return errors;
        }
    }
}

이렇게 예외처리를 분리해두면, 추후에 다른 에러 (RuntimeException, AccessDeniedException 등) 도 쉽게 처리할 수 있다.

---

🛠 Swagger 적용 + 버전 이슈 해결

Swagger는 정말 편한 도구인데, Spring Boot랑 버전이 살짝 안 맞으면 에러가 났다. 최근 버전에는 정식 지원을 하지 않는다는 것을 발견했다.

처음엔 Spring Boot 3.4.5를 쓰고 있었는데, Swagger 의존성을 추가하고 실행하자마자

“NoSuchMethodError: ControllerAdviceBean.()"

이런 에러가,,,
결론은 springdoc-openapi가 Spring Boot 3.4.5와 충돌이 있었던 거고,
결국 Spring Boot 버전을 3.2.3으로 내리고, Swagger는 2.2.0 버전으로 맞춰서 해결했다.

<!-- pom.xml -->
<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.2.3</version> <!-- 기존 3.4.5에서 다운그레이드 -->
</parent>

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.2.0</version>
</dependency>

---

🌐 Swagger UI 접속

서버를 재실행한 후 브라우저에서 아래 주소로 접속!

http://localhost:8080/swagger-ui/index.html

---

📌 Swagger 활용 꿀팁

• API를 직접 클릭해서 테스트 가능 (“Try it out”)
• JSON을 입력하면 POST 요청까지 다 가능
• 응답 코드, 스펙, 파라미터 전부 자동 정리됨
• 프론트 개발자한테 URL을 공유해서 테스트하기 편함

---

✨ 오늘 느낀 Swagger의 장점

기능	설명
자동 문서화	내가 만든 API들을 자동으로 정리해줌
협업 효율	프론트 개발자랑 일할 때 API 명세서를 따로 안 써도 될 것 같음
테스트 편의	Postman 없이 브라우저에서 다 해볼 수 있음
유지보수 편함	API가 늘어나도 문서도 같이 자동 업데이트됨

---

🔚 마무리

Swagger만 적용한 게 아니라, 버전 충돌도 직접 겪어보고 해결한 경험까지 할 수 있었고,
예외 처리 클래스를 도입해서 유효성 검사 응답도 훨씬 보기 좋게 정리하였다.

다음에는 본격적으로 프론트와 연동 준비를 시작해보자.

Repository : GitHub