如何基于format字段为Java的KeyValue配置Discriminator生成正确OpenAPI规范？

1. 对齐Jackson与OpenAPI注解的核心配置 #

首先要保证Jackson序列化/反序列化注解和OpenAPI鉴别器配置完全匹配，这是生成正确YAML的基础：

• 在KeyValue父类上添加Jackson的@JsonTypeInfo，指定类型识别字段为format，并使用名称作为类型标识：

  @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "format", visible = true)
  @JsonSubTypes({
      @JsonSubTypes.Type(value = PemKeyValue.class, name = "PEM"),
      @JsonSubTypes.Type(value = JwkKeyValue.class, name = "JWK"),
      // 补充其他KeyFormat对应的子类
  })
  

  其中visible = true是关键，它会保留format字段在序列化后的JSON中，确保OpenAPI能识别这个鉴别器字段。

2. 正确配置OpenAPI的@Schema注解 #

在KeyValue父类上补充@Schema注解，明确鉴别器属性和映射关系：

@Schema(
    discriminatorProperty = "format",
    discriminatorMapping = {
        @DiscriminatorMapping(schema = PemKeyValue.class, value = "PEM"),
        @DiscriminatorMapping(schema = JwkKeyValue.class, value = "JWK")
    },
    oneOf = {PemKeyValue.class, JwkKeyValue.class}
)
public abstract class KeyValue {
    @Schema(description = "密钥格式")
    private KeyFormat format;
    // 其他父类字段、getter/setter
}

• discriminatorProperty必须和Jackson@JsonTypeInfo里的property值完全一致（即format）
• discriminatorMapping的value要和KeyFormat的枚举值精准匹配，schema指向对应的子类
• oneOf列出所有可能的子类，确保OpenAPI规范中包含这些类型的完整定义

3. 规范子类的@Schema配置 #

每个KeyValue子类需要明确自身的@Schema标识，避免生成的规范出现歧义：

@Schema(description = "PEM格式的密钥数据")
public class PemKeyValue extends KeyValue {
    @Schema(description = "PEM格式的密钥内容")
    private String pemData;
    // getter/setter
}

4. 验证OpenAPI生成插件配置 #

如果使用SpringDoc OpenAPI或Swagger Maven插件，确保使用最新稳定版本（比如SpringDoc v2.x+），旧版本可能存在注解解析bug。同时检查插件是否扫描到KeyValue及其子类所在的包：

• 例如SpringDoc中，确保配置类覆盖了正确的扫描路径：

  @Configuration
  public class OpenApiConfig {
      @Bean
      public OpenAPI customOpenAPI() {
          return new OpenAPI()
                  .info(new Info().title("接口文档").version("v1"));
      }
  }
  

完成以上配置后重新生成OpenAPI YAML规范，规范中会包含format作为鉴别器字段，客户端即可基于该字段正确反序列化为对应的KeyValue子类。

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