为何Swagger无法识别可选JSON属性？Kotlin-Javalin场景求助

我之前也碰到过一模一样的情况，Javalin的OpenAPI插件在解析Kotlin数据类时，偶尔会忽略@JsonProperty(required = false)注解，错误地把带默认值的字段归为必填项。下面是几个经过验证的解决方案：

1. 配合使用OpenAPI原生@Schema注解 #

Jackson的@JsonProperty有时候和Javalin OpenAPI的解析逻辑兼容性不够，最好搭配OpenAPI自己的注解来显式标记字段可选：

首先确保你的项目引入了OpenAPI注解依赖（以Gradle为例）：

implementation 'io.swagger.core.v3:swagger-annotations:2.2.15' // 建议使用最新稳定版

然后修改Entity数据类中相关字段，补充@Schema(required = false)：

import io.swagger.v3.oas.annotations.media.Schema
// 其他导入语句...
data class Entity(
    val email: String,
    val name: String,
    val birthDate: DateTime,
    @JsonProperty(required = false) 
    @Schema(required = false)
    val gender: Gender? = null,
    @JsonProperty(required = false)
    @Schema(required = false)
    val country: String? = null,
    val locale: String,
    @Schema(required = false)
    val disabled: Boolean = false,
    @JsonProperty(required = false)
    @Schema(required = false)
    val createdAt: DateTime = DateTime(DateTimeZone.UTC),
    val role: Role,
    val entityTypeId: Long,
    @Schema(required = false)
    val entityTypeAttributes: MutableMap<String, Any> = HashMap(),
    val medicalSpecialityId: Long? = null,
    val id: Long? = null
)

插件会优先识别@Schema的标记，把这些字段从必填列表中移除。

2. 升级Javalin OpenAPI插件版本 #

旧版本的Javalin OpenAPI插件对Kotlin默认参数的解析存在bug，建议升级到最新稳定版。比如Gradle依赖配置：

implementation 'io.javalin:javalin-openapi:5.6.3' // 替换为当前最新版本号

新版本通常会修复这类Kotlin反射解析的问题。

3. 确认Kotlin反射依赖是否存在 #

Javalin处理Kotlin数据类需要依赖kotlin-reflect，如果项目中没有引入，可能导致默认参数无法被正确识别。添加对应依赖：

implementation "org.jetbrains.kotlin:kotlin-reflect:1.9.20" // 版本需和你的Kotlin版本匹配

验证效果 #

修改完成后重启服务，重新生成OpenAPI文档，就能看到createdAt、disabled等带默认值的字段不再出现在required数组里了。

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