如何在Swagger UI中覆盖OpenAPI Spec版本为Gradle项目版本

问题 #

我用OpenAPI 3.0.0规范的YAML文件定义Swagger UI，页面顶部会显示YAML里的版本。我想让Swagger直接用Gradle文件（build.gradle.kts）中的版本，避免每次手动修改两处，但之前通过OpenApiCustomiser修改/api-docs版本的方法无效——Swagger UI仍显示YAML文件里的占位版本。

我的相关配置如下：

build.gradle.kts #

version = "0.0.3" // 希望这个版本显示在Swagger页面上
group = "com.my.api"
java.sourceCompatibility = JavaVersion.VERSION_17
dependencies {
    ...
    implementation("org.springdoc:springdoc-openapi-webflux-ui:1.6.15")
}
springBoot {
    buildInfo()
}
openApiGenerate {
    generatorName.set("kotlin")
    inputSpec.set("$rootDir/src/main/resources/static/my-api-spec.yaml")
    outputDir.set("$buildDir/generated")
    modelPackage.set("com.my.api.web.model")
    globalProperties.set(mapOf(
        "apis" to "false",
        "apiDocs" to "false",
        "apiTests" to "false",
        "models" to "",
        "modelTests" to "false",
        "modelDocs" to "false",
        "invoker" to "false"
    ))
    configOptions.set(mapOf(
        "serializationLibrary" to "jackson",
        "sourceFolder" to ""
    ))
}
sourceSets {
    main {
        java.srcDir("$buildDir/generated")
    }
}
tasks.withType<KotlinCompile> {
    dependsOn(tasks.openApiGenerate)
    kotlinOptions {
        freeCompilerArgs = listOf("-Xjsr305=strict")
        jvmTarget = "17"
    }
}

src/main/resources/application.yml #

springdoc:
  swagger-ui:
    enabled: true
    url: /my-api-spec.yaml
    path: /swagger-ui.html
  api-docs:
    enabled: true
    path: /api-docs

src/main/resources/static/my-api-spec.yaml #

openapi: 3.0.0
info:
  title: My Little API
  description: "API for doing things"
  version: "placeholder" # 这个值总是显示在页面上

servers:
  - url: http://localhost:8080/
    description: "Local"

paths:
  /me:
    get:
      summary: "Get Current User Details"
      description: "Returns basic details about the current Authenticated User"
      responses:
        '200':
          description: "The Current Authenticated User's Details"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicUserInfo'
...

src/main/kotlin/com/my/api/Application.kt #

@SpringBootApplication
class MyLittleApplication {

    @Bean
    @ConditionalOnProperty(value = ["springdoc.swagger-ui.enabled"], havingValue = "true")
    fun swaggerCustomization(buildProperties: BuildProperties): OpenApiCustomiser {
        return OpenApiCustomiser { openApi ->
            openApi.info.version(buildProperties.version)
        }
    }
}

fun main(args: Array<String>) {
    runApplication<MyLittleApplication>(*args)
}

解决方案 #

问题根源在于：当前Swagger UI直接加载静态目录下的my-api-spec.yaml文件，而非经过OpenApiCustomiser处理后的/api-docs接口返回内容。以下是两种可行的解决方式：

方法一：让Swagger UI加载处理后的/api-docs接口 #

修改application.yml中Swagger UI的配置，将url指向/api-docs，这样页面就会使用你通过OpenApiCustomiser修改后的版本号：

springdoc:
  swagger-ui:
    enabled: true
    url: /api-docs # 替换原有的/my-api-spec.yaml
    path: /swagger-ui.html
  api-docs:
    enabled: true
    path: /api-docs

这种方式最简单，不需要额外的构建任务，直接复用你已有的OpenApiCustomiser配置即可。

方法二：构建时替换YAML文件中的版本占位符 #

如果必须保留Swagger UI加载本地YAML文件的逻辑，可以在Gradle构建过程中自动替换my-api-spec.yaml里的placeholder为项目版本。

在build.gradle.kts中添加以下任务：

tasks.register<Copy>("replaceApiVersion") {
    from("$rootDir/src/main/resources/static/my-api-spec.yaml")
    into("$buildDir/resources/main/static/")
    expand(mapOf("version" to project.version))
}

// 让processResources任务依赖这个替换任务
tasks.processResources {
    dependsOn(tasks.named("replaceApiVersion"))
    // 排除原文件，避免被复制到build目录
    exclude("static/my-api-spec.yaml")
}

然后修改my-api-spec.yaml中的版本占位符为Gradle变量格式：

info:
  title: My Little API
  description: "API for doing things"
  version: "${version}"

这样每次构建时，Gradle会自动将${version}替换为build.gradle.kts中定义的版本号，Swagger UI加载的就是替换后的YAML文件。

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