如何将我的 swagger 定义数组限制为 0 或 3

Question

我的 swagger 定义如下：

someDef:
    type: object
    properties:
      enable:
        type: boolean
        default: false
      nodes:
        type: array
        maxItems: 3
        items:
          type: object
          properties:
            ip:
              type: string
              default: ''

我的节点是数组，最大项目数：3。 我希望我的节点项目长度为 0 或 3。 提前致谢。

Answer 1

“0 或 3 个项目”可以在 OpenAPI 3.x (openapi: 3.x.x) 中定义，但不能在 OpenAPI 2.0 (swagger: '2.0' ).

打开API3.x

您可以将 oneOf 与 minItems 和 maxItems 结合使用来定义“0 或 3 项”条件：

# openapi: 3.0.0

nodes:
  type: array
  items:
    type: object
    properties:
      ip:
        type: string
        default: ''
  oneOf:
    - minItems: 0
      maxItems: 0
    - minItems: 3
      maxItems: 3

请注意，虽然 oneOf 是 OpenAPI 3.0 规范的一部分（即您可以编写包含 oneOf 的 API 定义），但实际工具支持 oneOf 可能会有所不同。

打开API 2.0

OAS 2 无法定义“0 项或 3 项”。您最多可以使用 maxItems: 3 来定义上限。