使用SpringDoc+Kotlin+WebFlux时出现白标错误页，无API文档生成

使用SpringBoot 3.0.2 + Kotlin 1.8.10 + WebFlux + SpringDoc（版本1.6.12）技术栈时，访问localhost:8080/v3/api-docs.yaml和localhost:8080/swagger-ui.html均返回白标错误页，未生成任何API文档。已按官方文档添加依赖，但问题依旧。

相关配置与代码如下：

依赖配置（build.gradle.kts） #

private object Version {
  const val kotlinCoroutinesVersion = "1.6.4"
  const val openApiVersion = "1.6.12"
}

plugins {
  val kotlinVersion = "1.8.10"

  id("org.springframework.boot") version "3.0.2"
  id("io.spring.dependency-management") version "1.1.0"
  id("org.jetbrains.kotlin.plugin.spring") version kotlinVersion
}


dependencies {

  // Coroutines dependencies
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:${Version.kotlinCoroutinesVersion}")
  runtimeOnly("org.jetbrains.kotlinx:kotlinx-coroutines-reactor:${Version.kotlinCoroutinesVersion}")

  // Spring dependencies
  implementation("org.springframework.boot:spring-boot-starter-webflux")

  // Swagger
  implementation("org.springdoc:springdoc-openapi-webflux-ui:${Version.openApiVersion}")
  implementation("org.springdoc:springdoc-openapi-kotlin:${Version.openApiVersion}")

  // Validation
  implementation("javax.validation:validation-api:2.0.1.Final")
}

控制器代码 #

@RestController
@RequestMapping("/product")
internal class OrderController(
  private val orderCommand: OrderCommand
) {

  @PostMapping
  suspend fun saveProduct(@Valid @RequestBody createOrderRequest: CreateOrderRequest): ResponseEntity<OrderCreatedResponse> {
    // Some code
  }
}

主类代码 #

@EnableWebFlux
@SpringBootApplication
class Application


fun main(args: Array<String>) {
  SpringApplication.run(Application::class.java, *args)
}

1. 修复SpringBoot 3.x与SpringDoc版本兼容问题 #

SpringBoot 3.0.x基于Jakarta EE 9，你当前使用的springdoc-openapi 1.6.12是针对SpringBoot 2.x（Java EE）的版本，两者不兼容。需升级SpringDoc到支持SpringBoot 3.x的版本（如2.0.2及以上）：

// 修改Version对象中的版本号
private object Version {
  const val kotlinCoroutinesVersion = "1.6.4"
  const val openApiVersion = "2.0.2"
}

同时，SpringBoot 3.x的验证API需替换为Jakarta版本，移除原javax依赖：

// 替换原validation依赖
implementation("jakarta.validation:jakarta.validation-api:3.0.2")
implementation("org.springframework.boot:spring-boot-starter-validation")

2. 移除@EnableWebFlux注解 #

使用spring-boot-starter-webflux时，SpringBoot已自动配置WebFlux环境，手动添加@EnableWebFlux会覆盖自动配置，导致SpringDoc相关Bean无法正常注册。修改主类：

@SpringBootApplication
class Application

fun main(args: Array<String>) {
  SpringApplication.run(Application::class.java, *args)
}

3. 调整控制器可见性 #

控制器使用internal修饰符会限制其仅模块内部可见，SpringDoc无法扫描到该类。将控制器改为默认public或显式声明：

@RestController
@RequestMapping("/product")
class OrderController(
  private val orderCommand: OrderCommand
) {
  // ...
}

4. 显式配置扫描路径（可选） #

若上述操作后仍未解决，可在application.yaml中指定SpringDoc扫描的包路径，确保控制器被识别：

springdoc:
  packages-to-scan: com.your.package.path # 替换为你的控制器所在包路径

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