数组中的 OpenAPI 多种类型

Question

我在使用 OpenAPI 3 定义可重用架构组件时遇到问题，该组件允许包含多种类型的数组。每个项目类型都继承自相同的父项 class，但具有特定的子属性。这似乎在 SwaggerHub 上的 model 视图中工作正常，但示例视图未正确显示数据。

TLDR; 有没有办法在 OpenAPI 3 中定义包含不同对象类型的数组？

Response:
  allOf:
    - $ref: '#/components/schemas/BaseResponse'
    - type: object
      title: A full response
      required:
      - things
      properties:
        things:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/ItemOne'
              - $ref: '#/components/schemas/ItemTwo'
              - $ref: '#/components/schemas/ItemThree'

Answer 1

您的规格是正确的。只是 oneOf 和 anyOf 模式的示例渲染在 Swagger UI 中尚不支持。您可以跟踪此问题以获取状态更新：

Multiple responses using oneOf attribute do not appear in UI

解决方法是在 oneOf/anyOf 架构旁边或父架构中手动添加 example：

        things:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/ItemOne'
              - $ref: '#/components/schemas/ItemTwo'
              - $ref: '#/components/schemas/ItemThree'
          # Note that array example is on the same
          # level as `type: array`
          example:
            - foo: bar        # Example of ItemOne
              baz: qux
            - "Hello, world"  # Example of ItemTwo
            - [4, 8, 15, 16, 23, 42]  # Example of ItemThree

数组中的 OpenAPI 多种类型

OpenAPI multiple types inside an array

swagger

swagger-ui

openapi