Kotlin SpringBoot3规范优先项目配置Springdoc Swagger UI及API文档URL

我们的Kotlin SpringBoot 3项目采用**规范优先（specification-first）**开发模式，通过openapi-generator从openapi.yml规范文件生成代码。现在需要发布API文档并展示Swagger UI页面，且URL需遵循以下约定：

• JSON规范可通过 http://localhost:8080/my-app/api/api-docs 访问
• Swagger UI可通过 http://localhost:8080/my-app/api/swagger-ui.html 访问

按相关配置建议操作后，yml文件被当作静态内容提供，无法满足上述URL约定，求解决办法。

更新补充信息 #

build.gradle.kts 代码片段（API代码生成配置） #

openApiGenerate {
  inputSpec.set("$rootDir/src/main/resources/static/my-app/api/openapi.yml")
  outputDir.set(outputDirPath.get().toString())
  packageName.set(apiPackageName)
  apiPackage.set("$apiPackageName.api")
  modelPackage.set("$apiPackageName.model")
  modelNameSuffix.set("Dto")
  generatorName.set("kotlin-spring")
  configOptions.set(
      mapOf(
          "useSpringBoot3" to "true",
          "delegatePattern" to "true",
          "interfaceOnly" to "false",
          "dateLibrary" to "java8",
          "useTags" to "true",
          "enumPropertyNaming" to "UPPERCASE"
      )
  )
}

代码生成在构建前执行，生成的代码正常，所有内容都在单个项目中。

Kotlin编译任务配置 #

tasks.withType<KotlinCompile> {
    dependsOn(tasks.openApiGenerate)
    mustRunAfter(tasks.openApiGenerate)
    kotlinOptions {
        freeCompilerArgs = listOf("-Xjsr305=strict")
        jvmTarget = "17"
    }
}

依赖项代码片段 #

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
    implementation("org.springframework.boot:spring-boot-starter-mustache")
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    implementation("org.springdoc:springdoc-openapi-data-rest:1.6.15")
    implementation("org.springdoc:springdoc-openapi-ui:1.6.15")
    implementation("org.springdoc:springdoc-openapi-kotlin:1.6.15")
    implementation("org.springframework.boot:spring-boot-starter-validation")
    developmentOnly("org.springframework.boot:spring-boot-devtools")
    /* 其他数据库和测试相关依赖 */
}

application.yml 配置片段 #

springdoc:
  api-docs:
    path: /api-docs
    groups:
      enabled: true
  swagger-ui:
    url: /my-app/api/openapi.yml
server:
  servlet:
    context-path: '/my-app/api'

结合你的配置和需求，按以下步骤调整即可实现目标：

1. 修正Springdoc配置 #

当前swagger-ui.url指向静态yml文件，导致Springdoc未使用自动生成的API文档。修改application.yml如下：

springdoc:
  api-docs:
    path: /api-docs  # 自动拼接server.context-path，最终路径为/my-app/api/api-docs
    groups:
      enabled: true
  swagger-ui:
    path: /swagger-ui.html  # 指定Swagger UI访问路径，拼接后为/my-app/api/swagger-ui.html
server:
  servlet:
    context-path: '/my-app/api'

注意：移除原swagger-ui.url配置，让Swagger UI默认对接Springdoc生成的/api-docs接口。

2. 确保Springdoc扫描到生成的API代码 #

若生成的API控制器不在Spring默认扫描包下，需在启动类指定扫描路径：

@SpringBootApplication(scanBasePackages = ["com.yourpackage.api"]) // 替换为实际的apiPackageName
@OpenAPIDefinition(info = Info(title = "My App API", version = "v1"))
class MyAppApplication

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

3. 调整openapi.yml存放路径 #

将openapi.yml从static目录移至非静态资源目录（如src/main/resources/api-spec），避免与Springdoc的API文档路径冲突，同时更新build.gradle.kts中的输入路径：

inputSpec.set("$rootDir/src/main/resources/api-spec/openapi.yml")

验证 #

启动项目后，验证以下地址：

• JSON规范：http://localhost:8080/my-app/api/api-docs
• Swagger UI：http://localhost:8080/my-app/api/swagger-ui.html

这样既满足URL约定，又能让Springdoc基于生成的API代码自动维护规范文档，而非直接提供静态文件。

内容的提问来源于stack exchange，提问作者Hermann.Gruber