Spring Boot Kotlin中String字段多枚举值OpenAPI生成问题

1. 当前代码及生成的规范是否有效？ #

无效。

• 你的DTO中identifier实际类型是String，但生成的OpenAPI规范将其标记为object，这与实际字段类型完全矛盾，会导致客户端误解字段格式（比如尝试发送JSON对象而非字符串），不符合OpenAPI规范的语义一致性要求。
• 你使用@Schema(oneOf = [...])的方式存在逻辑问题：springdoc-openapi在处理oneOf中的枚举类时，会默认将枚举视为独立的Schema对象，直接覆盖了你指定的type = "string"属性，最终生成错误的类型标记。

2. 更优的枚举值嵌入方式 #

推荐两种实用方案：

方案一：合并枚举值到allowableValues #

直接将两个枚举的所有取值合并，通过@Schema的allowableValues属性指定，生成的规范会正确标记字段类型为string，同时包含所有合法的枚举值：

data class MyDto(
    @Schema(
        type = "string",
        allowableValues = [
            "VALUE_A", "VALUE_B", // MyFirstEnum的取值
            "VALUE_X", "VALUE_Y"  // MySecondEnum的取值
        ]
    )
    val identifier: String,
    val someOtherField: String
)

如果枚举值较多，也可以通过代码动态生成合并后的常量，避免手动维护：

// 提前合并两个枚举的所有值
private val ALL_IDENTIFIER_VALUES = MyFirstEnum.values().map { it.name } + MySecondEnum.values().map { it.name }

data class MyDto(
    @Schema(
        type = "string",
        allowableValues = ALL_IDENTIFIER_VALUES.toTypedArray()
    )
    val identifier: String,
    val someOtherField: String
)

方案二：创建联合枚举接口（动态维护更优雅） #

定义一个接口让两个枚举实现，同时自定义转换器完成字符串到枚举的解析，springdoc会自动合并两个枚举的取值到OpenAPI规范中：

interface IdentifierEnum {
    val value: String
}

enum class MyFirstEnum(override val value: String) : IdentifierEnum {
    VALUE_A("VALUE_A"),
    VALUE_B("VALUE_B")
}

enum class MySecondEnum(override val value: String) : IdentifierEnum {
    VALUE_X("VALUE_X"),
    VALUE_Y("VALUE_Y")
}

// 自定义转换器，用于适配器层解析字符串
class IdentifierConverter : Converter<String, IdentifierEnum> {
    override fun convert(source: String): IdentifierEnum {
        return MyFirstEnum.values().firstOrNull { it.value == source }
            ?: MySecondEnum.values().firstOrNull { it.value == source }
            ?: throw IllegalArgumentException("无效的identifier: $source")
    }
}

// DTO中使用接口类型，springdoc会自动合并枚举值
data class MyDto(
    @Schema(type = "string")
    val identifier: IdentifierEnum,
    val someOtherField: String
)

这种方式的优势是枚举值可以随枚举类的修改自动更新，不需要手动维护注解内容。需要注意在Spring配置中注册自定义的IdentifierConverter，确保请求参数能正确解析为IdentifierEnum类型。

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