如何使用 OpenAPI/Swagger 定义数组项的排除类型？

Question

我已经试过了，但是Swagger UI不能渲染它，所以我猜测它是错误的:

      oneOf:
        - items:
          - $ref: '#/components/schemas/SchemaA'
        - items:
          - $ref: '#/components/schemas/SchemaB'

Answer 1

可以使用< code>oneOf来定义您的场景，如下所示:

oneOf:
  - type: array
    items:
      type: string
  - type: array
    items:
      type: integer
  - type: array
    items:
      $ref: '#/components/schemas/SchemaA'

在普通JSON模式中，type:array可以从oneOf，移到oneOf旁边，但我不确定OpenAPI是否允许这样做（OpenAPI规范对此不清楚）。

type: array
oneOf:
  - items:
      type: string
  - items:
      type: integer
  - items:
      $ref: '#/components/schemas/SchemaA'

我试过这个，但是Swagger UI无法渲染

目前，Swagger UI 不会自动为 oneOf 和 anyOf 架构生成示例（请参阅此问题）。解决方法是在 oneOf 手动旁边添加一个示例：

example: [1, 2, 3]  # <------
oneOf:
  - type: array
    items:
      type: string
  - type: array
    items:
      type: integer
  - type: array
    items:
      $ref: '#/components/schemas/SchemaA'