如何为 OpenAPI 中的每个索引（即元组）定义一个具有具体项目定义的 JSON 数组？

Question

我需要在 OpenAPI 中定义带有数组的 JSON 响应。该数组始终包含 2 个项目，第一个项目始终是数字，第二个项目始终是字符串。

[1, "a"]    //valid
["a", 1]    //invalid
[1]         //invalid
[1, "a", 2] //invalid

我发现 JSON 模式确实通过在

items

中传递项目列表而不是单个对象（source）来支持这一点，但 OpenAPI 明确禁止这样做，并且只接受单个对象（source）。那如何用 OpenAPI 来表达呢？

Answer 1

您需要 OpenAPI 3.1 来精确定义元组。在早期版本中，您只能定义没有特定项目顺序的通用数组。

开放API 3.1

您的示例可以定义为：

# openapi: 3.1.0

type: array
prefixItems:
  # The 1st item
  - type: integer
    description: Description of the 1st item

  # The 2nd item
  - type: string
    description: Description of the 2nd item

  # Define the 3rd etc. items if needed
  # ...

# The total number of items in this tuple
minItems: 2
maxItems: 2
additionalItems: false   # can be omitted if `maxItems` is specified

OpenAPI 3.1 与 JSON Schema 2020-12 完全兼容，包括

prefixItems

关键字（早期 JSON Schema 草案中 items 元组形式的新名称）。

OpenAPI 3.0.x 及更早版本

早期的 OpenAPI 版本没有描述元组的方法。您最多可以定义“一个由 2 个项目组成的数组，可以是数字或字符串”，但您不能具体定义第一个和第二个项目的类型。但是，您可以在架构中提及其他约束

description

。

# openapi: 3.0.0

type: array
items:
  oneOf:
    - type: integer
    - type: string
minItems: 2
maxItems: 2
description: >-
  The first item in the array MUST be an integer,
  and the second item MUST be a string.

如果您正在设计一个新的 API，而不是描述现有的 API，一种可能的解决方法是使用对象而不是数组来表示此数据结构。