如何在响应中指定未知数量的参数 Open API

Question

我正在尝试使用 swagger 和 Open API 3.0 规范为我的 API 建模。我已经制作了一些模式，现在我正在对我的端点的响应进行建模。问题是他们 return 是这样的：

[
 {
  "name": "this attribute is always here"
  "type1": { "description": "this maybe appear or not"  },
  "type2": { "description": "this maybe appear or not"  },
  ...
  "typeN": { "description": "N is not a fixed number, it may range from 0 to another positive integer"  },
 }
]

我知道如何为数组和对象建模（使用 name 属性）。当我必须对 typeX 属性建模时，问题就来了，我不知道如何指定它们是可选的并且出现的次数是可变的。有什么想法吗？

Answer 1

这个对象基本上是一个字符串到对象 dictionary/hashmap 加上一个额外的 name 属性。固定属性在 properties 中定义，字典部分可以使用 patternProperties（在 OpenAPI 3.1 中）或 additionalProperties（在 OpenAPI 3.0 和 2.0 中）定义。

OpenAPI 3.1

在 OAS 3.1 中，您的对象可以定义如下。由于可选的属性名称都遵循 typeX 格式，因此该架构使用 patternProperties 来定义属性名称的正则表达式。

MyObject:
  type: object
  required: [name]
  properties:
    name:
      type: string
  patternProperties:  # <-- This part defines the "typeX" properties
    ^type\d+$:        # <-- Property name regex
      type: object    # <-- Property value
      properties:
        description:
          type: string
  additionalProperties: false  # No other properties other than "name" and "typeX"

OpenAPI 3.0 和 2.0

在早期的 OAS 版本中，您使用 additionalProperties 来定义“可能有带有值的额外属性”，但是无法定义那些属性名称的格式。但是，您可以在模式描述中提及属性名称格式，还可以添加模式 example 用于文档目的。

MyObject:
  type: object
  description: >-
    In addition to the `name` property, this object may have an arbitrary
    number of properties named `typeX` where X is a positive integer.
  required: [name]
  properties:
    name:
      type: string
  additionalProperties:
    # This part defines the *value* of the typeX properties
    type: object
    properties:
      description:
        type: string

  # Optional schema example
  name: something
  type1:
    description: ....
  type2:
    description: ....

如何在响应中指定未知数量的参数 Open API

How to specify an unknown number of a parameter in the response Open API

openapi

OpenAPI 3.1

OpenAPI 3.0 和 2.0