SpringDoc + QueryDSL 충돌 문제 (2025-12-14)

[creepereye1204]

✅ 문제 요약

Spring Boot 4.0.0 환경에서 SpringDoc과 QueryDSL을 함께 사용할 때
버전 호환성 문제로 인해 의존성 충돌 및 빌드 오류가 발생.

---

✅ 상세 상황

• OS: Windows 11
• Java / Spring Boot: JDK 21 / Spring Boot 4.0.0
• 사용 라이브러리: SpringDoc, QueryDSL
• 증상:
  • Maven 빌드 시 의존성 충돌
  • SpringDoc OpenAPI UI 미동작
  • QueryDSL APT 생성 오류 또는 ClassNotFound 발생

---

✅ 원인 분석

1. Spring Boot 4.0.0은 생태계 호환성이 아직 부족

• Spring Boot 4.0.0은 정식 릴리스 전 단계
• SpringDoc, QueryDSL 등 주요 라이브러리가 아직 공식 지원하지 않음

2. SpringDoc이 Spring Framework 6.2 기반을 완전히 지원하지 않음

• Boot 4.0.0 → Spring Framework 6.2
• SpringDoc은 Spring 6.1까지 안정 지원
• WebMvcConfigurer, OpenAPI 자동 설정에서 충돌 발생

3. QueryDSL Jakarta EE 10 지원 미완성

• Boot 4.x는 Jakarta EE 10 기반
• QueryDSL 5.x는 Jakarta 지원이 불완전
• javax.persistence → jakarta.persistence 전환 과정에서 오류 발생

---

✅ 해결 방법

✅ 1. Spring Boot 버전을 3.4.12로 다운그레이드

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.4</version>
</parent>

• SpringDoc 2.x, QueryDSL 5.x와 완전 호환
• 실무에서 가장 추천되는 해결책

---

✅ 2. SpringDoc 최신 버전(2.x) 사용

(단, Boot 4.0.0에서는 정상 동작 보장 X)

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

• Boot 4.0.0에서는 정상 동작 보장 어려움

---

✅ 3. QueryDSL Jakarta 버전 명시

<dependency>
    <groupId>com.querydsl</groupId>
    <artifactId>querydsl-jpa</artifactId>
    <version>5.0.0</version>
    <classifier>jakarta</classifier>
</dependency>

<dependency>
    <groupId>com.querydsl</groupId>
    <artifactId>querydsl-apt</artifactId>
    <version>5.0.0</version>
    <classifier>jakarta</classifier>
</dependency>

✅ APT 플러그인 설정

<build>
    <plugins>
        <plugin>
            <groupId>com.mysema.maven</groupId>
            <artifactId>apt-maven-plugin</artifactId>
            <version>1.1.3</version>
            <executions>
                <execution>
                    <goals>
                        <goal>process</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>target/generated-sources/java</outputDirectory>
                        <processor>com.querydsl.apt.jpa.JPAAnnotationProcessor</processor>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

---

✅ 4. 대안: SpringDoc 대신 Spring REST Docs 사용

Boot 4.0.0을 반드시 사용해야 한다면
SpringDoc 대신 Spring REST Docs가 현실적인 대안.

---