Spring Boot 3 Kotlin：如何将带默认值字段标记为Swagger可选字段

原因分析 #

springdoc-openapi默认对Kotlin数据类的构造参数，即使带有默认值，也会标记为必填——因为Kotlin的默认值属于编译期特性，框架通过反射无法直接感知到默认值的存在，所以默认按必填规则处理。

方法一：用@Schema注解显式标记字段为非必填 #

在SomeRequest的name字段上添加@Schema注解，指定requiredMode为NOT_REQUIRED：

import io.swagger.v3.oas.annotations.media.Schema

data class SomeRequest(
    @Schema(requiredMode = Schema.RequiredMode.NOT_REQUIRED)
    val name: String = "some name"
)

方法二：配置springdoc自动识别Kotlin默认值 #

在配置文件中开启参数，让框架自动解析带默认值的字段为非必填，同时还会在OpenAPI文档中展示默认值：

application.properties #

springdoc.api-docs.resolve-schema-properties-default-values=true

application.yml #

springdoc:
  api-docs:
    resolve-schema-properties-default-values: true

额外优化建议 #

如果你的DTO是用来接收多个请求参数的，推荐在控制器参数上添加@ParameterObject注解，配合上述配置或注解使用，语义更清晰：

import io.swagger.v3.oas.annotations.ParameterObject

@RestController
@RequestMapping("/demo1")
class DemoController{
    @GetMapping
    fun demoM1(@ParameterObject request: SomeRequest) : String = "demo"
}

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