OpenAPI数组内的多种类型

Question

我在使用OpenAPI 3定义可重用的模式组件时遇到了麻烦，因为OpenAPI 3允许包含多种类型的数组。每个项类型都继承自同一父类，但具有特定的子属性。这似乎在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

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

OAS 3.0 Support Backlog Multiple responses using oneOf attribute do not appear in UI

解决方法是手动将example与oneOf / anyOf架构一起添加到父架构：

        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