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

Question

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

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

我发现JSON模式通过在items中传递项目列表而不是单个对象（源代码）来支持这一点，但OpenAPI明确禁止这一点，并且只接受单个对象（源代码）。如何在OpenAPI中表达？

Answer 1

OpenAPI 3.1与JSON模式2020-12完全兼容，包括prefixItems关键字（早期JSON模式草案中项的元组形式的新名称）。

你的例子可以定义为：

# 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版本没有描述元组的方法。您最多只能定义“一个由两个项目组成的数组，可以是数字或字符串”，但无法具体定义第一个和第二个项目的类型。但是，您可以在模式说明中提及其他约束。

# 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.