Question

Swagger documentation explains how to define arrays that contain mixed types，例如["foo", 5, -2, "bar"]。但是，如何定义数组必须包含一种类型的项目（字符串，["foo", "bar"]）或另一种类型（整数，[5, -2]）？

我已经尝试过了，但是Swagger UI无法渲染它，所以我想这是错误的：

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

Answer 1

首先，请记住，oneOf仅在OpenAPI 3.0（openapi: 3.0.0）中受支持，而在OpenAPI 2.0（swagger: '2.0'）中不受支持。

可以使用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模式生成示例（请参见this issue）。解决方法是手动在example旁边添加oneOf：

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

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

1 个答案: