如何在 OpenAPI 2.0 中定义混合类型数组（具有不同的元素类型）？

Question

我试图将以下 JSON 映射到 OpenAPI 2.0 (Swagger 2.0) YAML 定义，但我不确定如何将混合数组类型设置到我的架构中：

{
  "obj1": [
     "string data",
     1
    ]
}

现在，我的 OpenAPI 定义有：

schema:
  object1:
    type: array
    items:
      type: string

但这不允许数组中有整数。

有没有办法定义混合类型数组？

Answer 1

答案取决于您使用的 OpenAPI 规范版本。

OpenAPI 3.1

type 可以是类型列表，因此您可以将架构写为：

# openapi: 3.1.0

obj1:
  type: array
  items:
    type: [string, integer]
    # or if nulls are allowed:
    # type: [string, integer, 'null']

OpenAPI 3.0.x

OpenAPI 3.0 支持混合类型，使用 oneOf / anyOf 和可选的 nullable: true 也允许空值。

# openapi: 3.0.1

obj1:
  type: array
  items:
    oneOf:
      - type: string
        nullable: true  # If nulls are allowed
      - type: integer

OpenAPI 2.0

OpenAPI 2.0 (Swagger 2.0) 并不真正支持 mixed-type 数组和参数。您最多可以做的是对 items 使用 typeless schema {}，这意味着项目可以是任何东西（null 除外）——数字、objects、字符串等。您无法为 items 指定确切的类型，但您可以添加具有不同项目类型的数组的 example。

# swagger: '2.0'

obj1:
  type: array
  items: {}  # <--- means "any type" (except null)
  example:
    - string data
    - 1

注意： 无类型模式 {} 只能用于 body 参数和响应模式。路径、header 和表单参数需要原始数组项 type。

如何在 OpenAPI 2.0 中定义混合类型数组（具有不同的元素类型）？

How to define a mixed-type array (with different element types) in OpenAPI 2.0?

swagger

openapi

swagger-2.0

OpenAPI 3.1

OpenAPI 3.0.x

OpenAPI 2.0