如何在我的 Swagger UI 中覆盖/自定义 OpenAPI 规范版本？

Question

我不知道为什么这对我来说这么难，但我已经坚持了几个小时了。

我已经使用 yaml 文件和 openapi 3.0.0 规范为我的 API 定义了 Swagger UI。该规范需要定义一个版本，该版本显示在 Swagger 页面的顶部。但我希望我的 Swagger-UI 使用我的 Gradle 文件的版本，这样我就不必担心一直更改两个版本。但似乎没有任何作用。

有没有办法覆盖规范文件的版本？

这是我所拥有的：

构建.gradle.kts

version = "0.0.3" // <= I want this on my Swagger Page
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" # But this shows up no matter what

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'
...

我尝试过这个，但没有运气。它只是替换我的 /api-docs 中的版本，但 UI 会忽略它并使用规范文件的版本。

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)
}

Answer 1

您似乎希望根据 Gradle 项目的版本动态设置 Swagger UI 中显示的版本。对于

swaggerCustomization

bean，您走在正确的道路上，但您需要做一个小的改变。要在 OpenAPI 规范的“信息”部分设置版本属性，请使用

OpenApiCustomiser

。以下是调整您的

swaggerCustomization

bean 的方法：

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

此代码将动态地将 OpenAPI

info

部分中的版本设置为 Gradle 项目的版本。检查您的

build.gradle.kts

文件是否正确定义了

buildProperties

任务，如下所示：

tasks.register<BuildProperties>("buildProperties") {
    version = project.version.toString()
}