Spring Boot 3集成SpringDoc OpenAPI文档失效问题求助

问题背景 #

使用Spring Boot 3.0.0集成SpringDoc OpenAPI生成接口文档，已添加springdoc-openapi-ui依赖并刷新Maven，但访问默认链接时无法正常显示文档，页面报错（如图所示），怀疑存在依赖冲突，寻求排查方案。

核心排查步骤 #

1. 版本兼容性修正 #

Spring Boot 3.x基于Jakarta EE，而你使用的springdoc-openapi-ui:1.6.14是适配Spring Boot 2.x的版本，必须更换为Spring Boot 3.x兼容的2.x系列版本，同时依赖artifactId也有变更：

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

注意：Spring Boot 3.x不再使用旧版springdoc-openapi-ui，需改用springdoc-openapi-starter-webmvc-ui作为starter依赖

2. 依赖冲突排查 #

• 执行Maven命令生成依赖树，定位冲突JAR包：

  mvn dependency:tree
  

• 重点处理validation依赖冲突：Spring Boot自带的validation模块与手动引入的hibernate-validator:8.0.0.Final可能冲突，需从web starter中排除自带模块：

  <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
      <exclusions>
          <exclusion>
              <groupId>org.springframework.boot</groupId>
              <artifactId>spring-boot-starter-validation</artifactId>
          </exclusion>
      </exclusions>
  </dependency>
  

3. 访问路径与配置检查 #

• SpringDoc 2.x的默认访问路径变更为http://localhost:8082/swagger-ui/index.html，而非旧版的swagger-ui.html
• 检查application.properties是否有禁用Swagger的配置，确保没有类似以下内容，或显式开启：

  springdoc.swagger-ui.enabled=true
  

4. 启动日志分析 #

• 查看项目启动日志，搜索springdoc关键词，检查是否存在初始化失败、Bean创建异常、类找不到等报错信息
• 若出现ClassNotFoundException或NoClassDefFoundError，说明存在缺失或版本不匹配的依赖

5. 编译器版本修正 #

pom中maven-compiler-plugin的source和target设置为1.8，但项目使用Java 17，需同步修改：

<source>17</source>
<target>17</target>

原始配置信息 #

pom.xml #

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.0.0</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.openlab</groupId>
<artifactId>openlab-customer-service</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>openlab-customer-service</name>
<description>Demo project for Spring Boot customerservice</description>
<properties>
    <java.version>17</java.version>
    <spring-cloud.version>2022.0.0-RC2</spring-cloud.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.6.14</version>
    </dependency>

    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.hibernate.validator</groupId>
        <artifactId>hibernate-validator</artifactId>
        <version>8.0.0.Final</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>1.4.2.Final</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.github.classgraph</groupId>
            <artifactId>classgraph</artifactId>
            <version>4.8.139</version>
        </dependency>
    </dependencies>
</dependencyManagement>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludes>
                    <exclude>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                    </exclude>
                </excludes>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>1.8</source> <!-- depending on your project -->
                <target>1.8</target> <!-- depending on your project -->
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>1.18.16</version>
                    </path>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>1.4.2.Final</version>
                    </path>
                    <!-- other annotation processors -->
                </annotationProcessorPaths>
            </configuration>
        </plugin>

    </plugins>
</build>
<repositories>
    <repository>
        <id>netflix-candidates</id>
        <name>Netflix Candidates</name>
        <url>https://artifactory-oss.prod.netflix.net/artifactory/maven-oss-candidates</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

application.properties #

server.port=8082
spring.application.name=CUSTOMER-SERVICE
spring.h2.console.enabled=true
spring.cloud.discovery.enabled=false
spring.datasource.url=jdbc:h2:mem:customer-db

错误截图 #

内容的提问来源于stack exchange，提问作者Madiha Harifi