Question

我写了一个OpenAPI 3.0规范来定义一个对象，该对象必须引用其其他两个类继承其属性的抽象类。我使用Swagger Codegen CLI生成Java代码，并将对象用于序列化和反序列化，并且效果很好。现在，为了演示它，我想在Swagger UI上查看它。我使用this tutorial来呈现UI。但是，我无法获得正确的渲染。有趣的是，当我尝试在API规范中引用相同的内容时，它可以正常工作。

我的YAML规范文件分散在多个文件夹中，并且它们通过相对路径规范引用每个文件夹中的数据对象。

文件位置如下：

对象尝试使用抽象类的文件[whcih在UI上不起作用]：configuration / openapi / v3 / submit_request / v1 / ExecutionRequest.yaml
带有抽象类和继承类的文件[也很好地渲染]：配置/openapi/v3/inference/v1/invocation_request.yaml
带有API定义的文件[可在UI上使用]：配置/openapi/v3/inference/v1/api.yaml

我尝试过：

通读多态性，可以在网上的继承文章中寻求帮助，但是我没有找到一个示例，其中抽象类必须用于除API请求/响应之外的另一个对象中。
我尝试了各种组合来定义对象中的多态关系，但它们似乎破坏了代码源。

使用抽象类的对象：

ExecutionRequest:
      type: object
      properties:
        invocationData:
          type: InvocationsRequest
          description: |
            The type of invocation input data that is inputted. The invocation data can be submitted as
            reference or value. 
          oneOf:
            - $ref: "../../inference/v1/invocation_request.yaml#/components/schemas/ReferenceInvocationsRequest"
            - $ref: "../../inference/v1/invocation_request.yaml#/components/schemas/ValueInvocationsRequest"
          discriminator:
            propertyName: dataType
            mapping:
              value: '../../inference/v1/invocation_request.yaml#/components/schemas/ValueInvocationsRequest'
              reference: '../../inference/v1/invocation_request.yaml#/components/schemas/ReferenceInvocationsRequest'

抽象类定义：

InvocationsRequest:
      type: object
      description: |
        This is the abstract structure of invocations request. It discriminates based on dataType property.
      properties:
        dataType:
          $ref: '#/components/schemas/DataType'
      discriminator:
        propertyName: dataType
        mapping:
          value: '#/components/schemas/ValueInvocationsRequest'
          reference: '#/components/schemas/ReferenceInvocationsRequest'

正确定义的API定义

post:
      x-amzn-cpp-ai-input-dataType: InvocationsRequest
      x-amzn-cpp-ai-input-paramName: invocationsRequest
      description: This API serves the inference requests.
      requestBody:
        description: Input to the invocations API
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "../v1/invocation_request.yaml#/components/schemas/ReferenceInvocationsRequest"
                - $ref: "../v1/invocation_request.yaml#/components/schemas/ValueInvocationsRequest"

实际数据架构定义：

    DataType:
      description: |
        This is an enum denoting how data is being passed to the API. <br/>
        If the actual payload is passed in request then dataType is value.
        If the location of payload is passed in request then dataType is reference.
      type: string
      enum:
        - value
        - reference
    ReferenceInvocationsRequest:
      description: |
        This structure should be used for a reference to a 
        batch of records 
      x-discriminator-value: reference
      allOf:
        - $ref: '#/components/schemas/InvocationsRequest'
        - type: object
          properties:
            invocationsDataListRef:
              description: |
                Location of the serialized value of "#/components/schemas/InvocationsDataList"
              type: string
    ValueInvocationsRequest:
      description: |
        This structure should be used when an inline batch of records 
        is passed
      x-discriminator-value: value
      allOf:
        - $ref: '#/components/schemas/InvocationsRequest'
        - type: object
          properties:
            invocationsDataList:
              description: |
                Batch of all records provided as input
              type: array
              items:
                $ref: "#/components/schemas/InvocationsData"
    InvocationsData:
      description: Structure containing data
      type: object
      required:
        - dataIdentifier
        - dataList
      properties:
        dataIdentifier:
          description: Unique data identifier
          type: string
        dataList:
          description: List of data-elements.
          type: array
          items:
            $ref: "#/components/schemas/Data"
    Data:
      description: Structure representing the data passed in request.
      type: object
      required:
        - namespace
        - data
      properties:
        namespace:
          description: A unique identifier representing the data namespace.
          type: string
        data:
          description: |
            the actual data/location of data.
          type: string

UI错误屏幕截图：

Swagger UI model rendering

我认为我可以清楚地看到渲染中的错误是递归数据类型的路径。我不确定为什么要这么做。

用于OpenAPI 3.0规范的oneOf的Swagger UI渲染问题

0 个答案: