Springdoc 2.7.0 업그레이드 후 ClassNotFoundException: LiteWebJarsResourceResolver 에러 해결하기

Problem

Spring Boot 프로젝트에서 API 문서화를 위해 사용 중인 springdoc 라이브러리의 버전을 2.6.x에서 2.7.x로 업그레이드할 때 애플리케이션 실행이 실패하는 문제가 발생할 수 있습니다. 이때 콘솔에는 ClassNotFoundException: org.springframework.web.servlet.resource.LiteWebJarsResourceResolver라는 에러 메시지와 함께 ApplicationContext 로드 실패 로그가 출력됩니다. 이는 코드 변경 없이 단순히 의존성 버전만 올렸음에도 불구하고 테스트나 애플리케이션 구동 시 즉각적으로 나타나는 치명적인 에러입니다.

Background

이 에러의 근본적인 원인은 라이브러리 간의 버전 호환성(Compatibility) 문제입니다. 에러 로그에 명시된 LiteWebJarsResourceResolver 클래스는 Spring Framework 6.2 버전에서 새롭게 도입되었습니다. 하지만 Spring Boot 3.3.x 버전은 하위 버전인 Spring Framework 6.1.x를 기반으로 동작합니다. 즉, Springdoc 2.7.x는 Spring Boot 3.4.x(Spring 6.2.x) 환경을 타겟으로 릴리즈되었기 때문에, Spring Boot 3.3.x 환경에서 실행하면 존재하지 않는 클래스를 참조하려다 ClassNotFoundException이 발생하게 되는 것입니다.

Solution

이 문제를 해결하는 방법은 현재 프로젝트의 상황에 따라 두 가지로 나눌 수 있습니다. Springdoc 공식 호환성 매트릭스를 참고하여 버전을 맞춰주어야 합니다.

1. Spring Boot 3.3.x를 유지해야 하는 경우 (Springdoc 다운그레이드)

프로젝트의 Spring Boot 버전을 당장 올릴 수 없다면, Springdoc 버전을 2.6.x로 롤백해야 합니다.

Maven (pom.xml)

<!-- Spring Boot 3.3.x 환경에서는 springdoc 2.6.0 버전을 사용합니다. -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

Gradle (build.gradle)

// Spring Boot 3.3.x 환경에서는 springdoc 2.6.0 버전을 사용합니다.
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

2. Springdoc 2.7.x를 사용하고 싶은 경우 (Spring Boot 업그레이드)

최신 버전의 Springdoc을 사용해야 한다면, Spring Boot 버전을 3.4.x 이상으로 업그레이드해야 합니다.

Gradle (build.gradle)

plugins {
    // Spring Boot 버전을 3.4.x로 업그레이드합니다. (Spring Framework 6.2.x 포함)
    id 'org.springframework.boot' version '3.4.0'
    id 'io.spring.dependency-management' version '1.1.4'
    id 'java'
}

dependencies {
    // 이제 springdoc 2.7.0 버전을 안전하게 사용할 수 있습니다.
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'
}

💡 Springdoc - Spring Boot 호환성 매트릭스

버전 충돌을 방지하기 위해 아래의 호환성 표를 기억해두는 것이 좋습니다.

Deep Dive

Spring 생태계에서 서드파티 라이브러리(Springdoc, QueryDSL 등)를 업데이트할 때는 항상 Spring Framework 및 Spring Boot와의 호환성을 먼저 확인해야 합니다. 특히 메이저나 마이너 버전이 올라갈 때는 내부적으로 사용하는 코어 클래스가 변경되거나 삭제되는 경우가 많습니다. 프로덕션 환경에서 이러한 문제를 예방하려면, 의존성 업데이트 시 공식 문서의 릴리즈 노트(Release Notes)를 확인하는 습관을 들여야 합니다. 또한, Dependabot과 같은 자동화 도구를 사용할 때도 CI/CD 파이프라인의 자동화된 테스트를 통해 이러한 ClassNotFoundException 런타임 에러를 사전에 필터링할 수 있도록 견고한 통합 테스트 환경을 구축하는 것이 중요합니다.

Conclusion

요약하자면, LiteWebJarsResourceResolver 관련 ClassNotFoundException은 Spring Boot(Spring Framework)와 Springdoc 간의 버전 불일치로 인해 발생합니다. 프로젝트의 상황에 맞게 Spring Boot 버전을 3.4.x로 올리거나, Springdoc 버전을 2.6.x로 유지하여 호환성을 맞춰주면 문제가 깔끔하게 해결됩니다.

References

• Springdoc-openapi 공식 문서
• Spring Boot 3.4 Release Notes