[Swagger] Spring, Spring Boot 호환되는 버전 정리

springdoc-openapi × Spring Boot 버전 불일치로 Swagger `/api-docs` 가 500을 뿜었던 기록

최근 사내 AI 서빙 모놀리식을 Spring Boot 3.x 로 올리면서
Swagger-UI(/swagger-ui), OpenAPI JSON(/api-docs) 가 500 Internal Server Error 를 내뿜는 대참사가 있었다.
검색하면 흔히 나오는 “순환 참조”‧“Security 설정” 문제와는 달리, 이번엔 버전 호환성이 주범이었다.

 

1. 증상

요청	결과
`GET /swagger-ui`	UI는 뜨지만 “Failed to load API definition” 경고
`GET /api-docs` (또는 `/v3/api-docs`)	**500 Internal Server Error**

콘솔 로그에는 대략 이런 예외가 줄줄이 찍힌다.

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

또는

java.lang.NoClassDefFoundError:
  org/springdoc/core/models/GroupedOpenApi

---

2. 원인 분석

1. Spring Boot 3.3.x (Framework 6.2) 로 업그레이드
2. 기존에 쓰던 springdoc-openapi-starter-webmvc-ui 2.5.0 유지
3. → Boot 3.3 가 의존하는 Spring 6.2 에서 ControllerAdviceBean(Object) 생성자가 제거
4. springdoc 2.5.0 코드는 그 생성자를 호출 → NoSuchMethodError

핵심 : Spring Boot / Spring Framework 버전이 올라갈 때마다 springdoc 쪽도 “짝”이 맞는 버전으로 함께 올려야 한다.

---

3. 해결 과정 TL;DR

1. dependency tree 로 실제 런타임 버전 확인
2. ./gradlew :ai-playground:dependencies --configuration runtimeClasspath \ | grep -E "spring-web[^a-zA-Z]|springdoc-openapi"
3. 버전 호환표 를 기준으로 Spring Boot ↔ springdoc 버전을 세트로 맞춤
4. ./gradlew --refresh-dependencies clean build 후 재기동
5. /api-docs 200 OK → Swagger-UI 정상 렌더링

---

4. Spring Boot 2.7 ~ 3.5 호환 표 📋

Spring Boot	Spring Framework	공식 호환 springdoc	권장 GA
3.5.x	6.4.x	2.8.9 이상	2.8.9
3.4.x	6.3.x	2.7 – 2.8.x	2.8.9
3.3.x	6.2.x	2.6.x	2.6.4
3.2.x (LTS)	6.1.x	2.3 – 2.5.x	2.5.0
3.1.x	6.0.x	2.2.x	2.2.2
3.0.x	6.0.x	2.0.x 이상	2.2.2
2.7.x	5.3.x	1.6.11 이상 1.x	1.8.0

---

5. 실전 적용 예시 (Boot 3.2.x + springdoc 2.5.0)

// settings.gradle.kts
pluginManagement {
    plugins {
        id("org.springframework.boot") version "3.2.9"
        id("io.spring.dependency-management") version "1.1.7"
    }
    repositories { gradlePluginPortal(); mavenCentral() }
}

// build.gradle.kts
dependencies {
    implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0")
}

모듈별 build.gradle.kts 에 Boot 버전을 따로 적지 말 것!
pluginManagement 쪽 버전이 자동 전파된다.

---

6. 마무리 — 교훈

1. Spring Boot ↔ springdoc 버전 호환표를 항상 같이 확인하자.
2. 버전 업이 필요할 땐 의존성 트리부터 찍어 보고,
   겹치는 라이브러리(특히 springdoc 1.x vs 2.x) 가 없는지 검증하자.
3. SNAPSHOT/RC 에 의존해야 할 땐 CI 캐시 + 사내 Nexus 핀업이 필수!

덕분에 Swagger가 다시 살아났고, 빌드/배포 파이프라인에도 버전 검증 스텝을 추가했다.