springdoc-openapi-gradle-plugin与Spring Boot 3.2.5兼容吗？生成文档遇连接失败

核心问题：版本不兼容 #

Spring Boot 3.x 基于Jakarta EE规范，而你使用的springdoc-openapi-gradle-plugin:1.8.0和springdoc-openapi-ui:1.8.0是适配Spring Boot 2.x（基于Java EE）的版本，二者存在底层API依赖冲突，这是导致无法正常生成文档的主要原因。

解决步骤 #

1. 升级springdoc相关依赖和插件版本 #

修改build.gradle中的插件和依赖版本，适配Spring Boot 3.2.5：

plugins {
    id("org.springframework.boot") version "3.2.5"
    // 替换为适配Spring Boot 3的插件版本
    id("org.springdoc.openapi-gradle-plugin") version "2.2.0"
}

dependencies {
    // 移除旧的springdoc依赖，替换为适配Spring Boot 3的版本
    implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0")
    implementation("org.springdoc:springdoc-openapi-kotlin:2.5.0")
    // 其他依赖保持不变
    implementation("org.springframework.boot:spring-boot-starter-actuator")
    implementation("org.springframework.boot:spring-boot-starter-webflux")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-test")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

2. 验证API文档路径 #

Spring Boot 3.x搭配springdoc v2.x时，默认的YAML格式API文档路径是http://localhost:8080/v3/api-docs.yaml，你的配置是正确的，但需要确保应用启动后能正常访问该路径：

• 手动启动TestConfiguration并激活test profile，用浏览器或curl访问该地址，确认能返回YAML格式的文档内容。

3. 处理Web与WebFlux共存问题 #

你同时引入了spring-boot-starter-web和spring-boot-starter-webflux，Spring Boot会默认使用WebFlux的Netty服务器而非Tomcat；若日志显示Tomcat启动，需确认是否有自定义配置强制切换服务器，同时检查8080端口无占用情况。

4. 调整任务配置细节 #

可适当调整等待时间，确保应用完全启动后再尝试拉取文档：

openApi {
    apiDocsUrl.set("http://localhost:8080/v3/api-docs.yaml")
    outputDir.set(file("src/main/resources"))
    outputFileName.set("test.swagger")
    waitTimeInSeconds.set(60) // 根据实际启动速度调整时长

    customBootRun{
        classpath.setFrom(sourceSets["test"].runtimeClasspath)
        mainClass.set("xxx.TestConfiguration")
        args.set(listOf("--spring.profiles.active=test"))
    }
}

tasks.named("generateOpenApiDocs") {
    dependsOn("testClasses")
    mustRunAfter("testClasses")
}

额外检查点 #

• 确认application-test.yml中的springdoc.api-docs.enabled=true配置未被其他配置覆盖。
• 查看应用启动日志，确认存在SpringDoc开头的初始化日志，说明springdoc组件已正常加载。

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