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

Question

我正在开发一个带有 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

Answer 1

如果您可以修改您的 swagger，则可以将 替换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

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

Answer 2

目前，openapi-generator 不支持oneOf. 这是 OpenAPI v3 新引入的一项功能（仅供参考，只有 v2 及以下版本称为“Swagger”，后来更名为 OpenAPI）。有各种生成器（Java、Spring、许多其他语言）。我看到今年已经做出贡献以提供oneOf支持。

总而言之，在使用 Spring 生成器来利用 OpenAPI v3 规范的此功能之前，您似乎还需要等待一段时间。

编辑：它也列在“短期路线图”中：

OAS3.0 特性支持：anyOf、oneOf、回调等

Answer 3

我们为一些生成器添加了更好的 oneOf 和 anyOf 支持，例如java(okhttp-gson、jersey2、native)、csharp-netcoreGo、PowerShell、R 等。请使用最新的大师来尝试一下。快照版本可以在项目的自述文件中找到： https: //github.com/OpenAPITools/openapi-generator/