OpenAPI Generator生成的子类型未实现AnimalRefOrValue接口求助

我没有Swagger和OpenAPI Generator使用经验，现在尝试用它们创建并生成模型。目前遇到的问题是：Swagger中定义的AnimalRefOrValue是一个接口，但生成的所有子类型（Cat/Dog/Animal）都没实现这个接口，导致开发映射器时，类型为AnimalRefOrValue的属性无法接收任何子类型实例。

现有Swagger定义 #

# AnimalRefOrValue 定义
AnimalRefOrValue:
  type: object
  description: >
    The polymorphic attributes @species, @schemaLocation & @referredType are related to the Animal
    entity and not the AnimalRefOrValue class itself.
  oneOf:
    - $ref: '#/components/schemas/Animal'
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
  discriminator:
    propertyName: "@species"
    mapping:
      Animal: '#/components/schemas/Animal'
      Cat: '#/components/schemas/Cat'
      Dog: '#/components/schemas/Dog'

# Cat 定义
Cat:
  allOf:
    - $ref: '#/components/schemas/Animal'
    - type: object
      description: >
        A specific type of animal with unique properties.
      required:
        - "@species"
      properties:
        meowVolume:
          type: string
          description: Volume of the cat's meow.
        furColor:
          type: string
          description: Color of the cat's fur.
        relatedAnimals:
          type: array
          items:
            $ref: '#/components/schemas/AnimalRefOrValue'
          description: This is an array of related animals.
        @species:
          type: string

生成的Java代码示例 #

// AnimalRefOrValue 接口
@JsonIgnoreProperties(
    value = "@species", // ignore manually set @species, it will be automatically generated by Jackson during serialization
    allowSetters = true // allows the @species to be set during deserialization
)
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "@species", visible = true)
@JsonSubTypes({
    @JsonSubTypes.Type(value = Animal.class, name = "Animal"),
    @JsonSubTypes.Type(value = Cat.class, name = "Cat"),
    @JsonSubTypes.Type(value = Dog.class, name = "Dog")
})
@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2025-01-14T16:33:35.582270100-03:00")
public interface AnimalRefOrValue {
    public String getSpecies();
}

// Cat 类（未实现AnimalRefOrValue接口）
@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2025-01-14T16:33:35.582270100-03:00") 
public class Cat extends Animal {
    @JsonProperty(value = "meowVolume")
    @JsonPropertyDescription("Volume of the cat's meow.")
    private String meowVolume;
    @JsonProperty(value = "furColor")
    @JsonPropertyDescription("Color of the cat's fur.")
    private String furColor;
    @Valid
    @JsonProperty(value = "relatedAnimals")
    @JsonPropertyDescription("This is an array of related animals.") 
    private List<@Valid AnimalReforValue> relatedAnimals = null;
    @JsonProperty(value = "@species", required = true) 
    @JsonPropertyDescription("Species type of the animal.")
    private String species;
    
    public Cat meowVolume(String meowVolume) {
        this.meowVolume = meowVolume;
        return this;
    }
}

解决方案 #

1. 修改Swagger定义，调整多态结构（推荐）

把AnimalRefOrValue从oneOf的组合类型改成基类/接口的定义方式，让所有子类型通过allOf继承它：

# 修改后的AnimalRefOrValue定义
AnimalRefOrValue:
  type: object
  description: >
    多态属性@species、@schemaLocation和@referredType属于Animal实体，而非AnimalRefOrValue类本身。
  required:
    - "@species"
  properties:
    "@species":
      type: string
  discriminator:
    propertyName: "@species"
    mapping:
      Animal: '#/components/schemas/Animal'
      Cat: '#/components/schemas/Cat'
      Dog: '#/components/schemas/Dog'

# 修改后的Cat定义
Cat:
  allOf:
    - $ref: '#/components/schemas/AnimalRefOrValue'
    - $ref: '#/components/schemas/Animal'
    - type: object
      description: >
        一种具有独特属性的特定动物类型。
      properties:
        meowVolume:
          type: string
          description: 猫叫的音量。
        furColor:
          type: string
          description: 猫毛的颜色。
        relatedAnimals:
          type: array
          items:
            $ref: '#/components/schemas/AnimalRefOrValue'
          description: 相关动物的数组。

这样OpenAPI Generator会自动识别AnimalRefOrValue为基接口，让Animal、Cat、Dog类自动实现它。

2. 用生成器配置参数强制接口实现

如果不想修改Swagger定义，可以在生成代码时添加配置参数：

• 若用config.json配置：

{
  "interfaceImplementations": {
    "AnimalRefOrValue": ["Animal", "Cat", "Dog"]
  }
}

• 若用命令行生成：

openapi-generator generate -i swagger.yaml -g spring --additional-properties interfaceImplementations=AnimalRefOrValue:Animal,Cat,Dog

这个参数会强制生成的子类型类实现AnimalRefOrValue接口。

3. 手动修改生成代码（临时方案）

如果以上方法暂时无法操作，可以手动修改Java类，让它们实现接口：

public class Cat extends Animal implements AnimalRefOrValue {
    // 原有代码无需改动，因为已经包含getSpecies()方法
}

注意：每次重新生成代码会覆盖手动修改的内容，仅适合临时测试。

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