生成 Spring 代码时如何将 OpenAPI“oneOf”属性与 openapi-generator-maven-plugin 一起使用答案

【问题标题】：How to use OpenAPI "oneOf" property with openapi-generator-maven-plugin when generating Spring code生成 Spring 代码时如何将 OpenAPI“oneOf”属性与 openapi-generator-maven-plugin 一起使用
【发布时间】：2020-10-26 19:40:03
【问题描述】：

我正在开发一个带有 Angular 前端和 RESTful Spring Boot 后端的应用程序

我从 org.openapitools 找到了这个非常方便的 maven 插件 openapi-generator-maven-plugin。凭借其代码生成功能，它有助于在我们的 API 的前端和后端之间实施“合同优先”的方法。但是我们的 swagger 文件在 requestBody 和 responseBody 定义中使用了“oneOf”属性。我试图从中生成 Spring 代码，但生成的 Java 类缺少导入：

import com.pack.api.dto.OneOfLatteCoffeAmericanoCoffe;
import com.pack.api.dto.UNKNOWN_BASE_TYPE;

是否可以将插件与 Swagger 的 oneOf 属性一起使用？我正在使用 Spring Boot 2.3.1、Swagger 3.0 和 Openapi-generator-maven-plugin 4.3

【问题讨论】：

标签： spring-boot code-generation maven-plugin openapi-generator

【解决方案1】：

目前，openapi-generator 不支持oneOf。这是 OpenAPI v3 新引入的功能（仅供参考，只有 v2 及以下版本称为“Swagger”，然后已重命名为 OpenAPI）。有各种生成器（Java、Spring、许多其他语言）。我在今年看到contributions have been made 到enable oneOf support。

总而言之，在您可以使用 Spring 生成器利用 OpenAPI v3 规范的这一特性之前，您似乎需要再等一会儿。

编辑：它也列出了on the "short term roadmap"：

OAS3.0 功能支持：anyOf、oneOf、回调等

【讨论】：

我一直在努力为大量使用 anyOf 和 oneOf 的 API 生成 PHP 客户端。经过一些谷歌搜索并发现围绕这个主题的堆栈溢出问题令人惊讶地很少，我猜对多态性的支持真的是代码生成的一个强大的 WIP 主题？
刚刚也遇到了这个问题:(

【解决方案2】：

如果您可以修改您的招摇，您可以将oneOf 替换为对抽象类型的引用。

例如，如果你的招摇看起来像这样：

components:
  schemas:
    'Parent':
      'vehicle':
        oneOf:
        - type: object
          properties:
            'car_property':
              type: string
        - type: object
          properties:
            'truck_property':
              type: string

你可以这样修改：

components:
  schemas:
    'Parent':
      type: object
      properties:
        'vehicle':
          $ref: '#/components/schemas/Vehicle'
    #---------------------------------------------------------------------------
    # Abstract class with discriminator 'vehicle_type'
    #---------------------------------------------------------------------------
    'Vehicle':
      type: object
      properties:
        'vehicle_type':
          type: string
          enum: [ 'CAR', 'TRUCK' ]
      discriminator:
        propertyName: vehicle_type
        mapping:
          'CAR': '#/components/schemas/Car'
          'TRUCK': '#/components/schemas/Truck'
    #---------------------------------------------------------------------------
    # Concrete classes
    #---------------------------------------------------------------------------
    'Car':
      allOf:
      - $ref: "#/components/schemas/Vehicle"
      - type: object
        properties:
          'car_property':
            type: string
    'Truck':
      allOf:
      - $ref: "#/components/schemas/Vehicle"
      - type: object
        properties:
          'truck_property':
            type: string

这种大摇大摆的修改使生成器工作。它处理相同的 JSON 对象，尽管我不能 100% 确定它在 OpenAPI 规范中的语义等价。

【讨论】：

在尝试此解决方案时，我仍然在抽象模型中得到：@JsonSubTypes({ @JsonSubTypes.Type(value = ERRORUNKNOWN.class, name = "Obj1"), @JsonSubTypes.Type(value = ERRORUNKNOWN.class, name = "Obj2"), })，编译失败。

【解决方案3】：

我们为java (jersey2)、csharp-netcore 等一些生成器添加了更好的 oneOf 和 anyOf 支持。请用最新的大师试一试。 SNAPSHOT 版本可以在项目的 README 中找到：https://github.com/OpenAPITools/openapi-generator/

【讨论】：

maven available 5.1.1 不支持 oneof 和 anyof 代码生成。 5.2.0-SNAPSHOT 和 6.0.0-SNAPSHOT 在 maven 上不可用。如果这两个版本支持其中一个，你建议如何尝试？必须在生产代码中使用此实用程序。

【解决方案4】：

对我来说，创建的 csharp 生成的模型对象不正确。它会生成以下内容，

[DataMember(Name = "category", IsRequired = true, EmitDefaultValue = true)]
public OneOfobjectobjectobject Category { get; set; }

它创建一个以单词 Oneof 开头的对象并附加三个对象，因为我的 openapi 规范文档中有三个 oneOfs 用于类别。有没有办法返回字典或其他东西？上面的代码无法编译。我的类别的 openapi 架构如下

category:
          title: Category
          oneOf:
            - title: Year
              type: object
              properties:
                type:
                  title: Type
                  enum:
                    - year
                  type: string
              additionalProperties: false
              required:
                - type
            - title: Term
              type: object
              properties:
                type:
                  title: Type
                  enum:
                    - term
                  type: string
                parent:
                  title: Parent
                  oneOf:
                    - title: Academic Period
                      type: object
                      properties:
                        academicPeriod:
                          title: Academic Period
                          type: object
                          properties:
                            id:
                              title: ID
                              description: The global identifier for the Academic Period.
                              type: string
                              format: guid
                              pattern: ^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$
                          additionalProperties: false
                          required:
                            - id
                      additionalProperties: false
                      required:
                        - academicPeriod
                    - title: Academic Year
                      type: object
                      properties:
                        academicYear:
                          title: Academic Year
                          type: number
                      additionalProperties: false
                      required:
                        - academicYear
                preceding:
                  title: Preceding
                  oneOf:
                    - type: object
                      properties:
                        id:
                          title: ID
                          description: The global identifier for the Preceding.
                          type: string
                          format: guid
                          pattern: ^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$
                      additionalProperties: false
                      required:
                        - id
                    - type: object
                      maxProperties: 0
              additionalProperties: false
              required:
                - type
            - title: Subterm
              type: object
              properties:
                type:
                  title: Type
                  enum:
                    - subterm
                  type: string
                parent:
                  title: Parent
                  type: object
                  properties:
                    id:
                      title: ID
                      description: The global identifier for the Parent.
                      type: string
                      format: guid
                      pattern: ^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$
                  additionalProperties: false
                  required:
                    - id
                preceding:
                  title: Preceding
                  oneOf:
                    - type: object
                      properties:
                        id:
                          title: ID
                          description: The global identifier for the Preceding.
                          type: string
                          format: guid
                          pattern: ^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$
                      additionalProperties: false
                      required:
                        - id
                    - type: object
                      maxProperties: 0
                sectionDateOverride:
                  title: Section Date Override
                  oneOf:
                    - type: string
                      enum:
                        - notAllowed
                    - type: string
                      maxLength: 0
              additionalProperties: false
              required:
                - type
                - parent

【讨论】：