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当前没有描述元组的方法。您所能做的就是定义“由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，则可能的解决方法是使用对象而不是数组来表示此数据结构。

以下是与您的用例相关的现有OpenAPI增强请求：

如何在OpenAPI中使用每个索引的具体项目定义来定义JSON数组？

1 个答案: