tuples - 如何为 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

开放API 3.1
OpenAPI 3.1 与 JSON Schema 2020-12 完全兼容，包括 prefixItems关键字(来自早期 JSON 模式草案的 tuple form of items 的新名称)。
您的示例可以定义为:

type: array
prefixItems:
  - type: integer
  - type: string
minItems: 2
maxItems: 2
additionalItems: false   # can be omitted if `maxItems: 2` is specified

OpenAPI 3.0.x 及更早版本
早期的 OpenAPI 版本没有描述元组的方法。您最多可以定义“可以是数字或字符串的 2 个项目的数组”，但您不能具体定义第 1 项和第 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，可能的解决方法是使用对象而不是数组来表示此数据结构。