查询参数阵列中的数字索引是否在Swagger 2.0中表示？

Question

我了解如何用Swagger 2.0表示查询参数中的数组：

?list=x&list=y

是否可以使用索引样式在Swagger 2.0中表示数组？

?list[0]=x&list[1]=y

Answer 1

OpenAPI 2.0（FKA Swagger 2.0）

list [0]，list [1]，list> list [2] ... ... list [list [list] [ n]必须定义为单独的查询参数。无法将list定义为单个数组类型参数，并以您想要的方式序列化。

请注意，此方法仅适用于提前已知最大尺寸的固定尺寸阵列。

parameters:
  - in: query
    name: list[0]
    type: string
  - in: query
    name: list[1]
    type: string

OpenAPI 3.0

一种方法是定义list [0]，list [1]等作为单独的查询参数（例如，在OpenAPI 2.0示例中）。此方法适用于预先已知最大尺寸的固定尺寸阵列。

parameters:
  - in: query
    name: list[0]
    schema:
      type: string
  - in: query
    name: list[1]
    schema:
      type: string

另一种适用于未知大小数组的方法是使用 free -form查询参数。这种方法的限制在于，它允许任意参数名称 - 不仅是list [n]，还abcde。但是，您可以提供描述解释参数名称必须以格式list [n]，并且提供示例>示例值值文档目的。

parameters:
  - in: query
    name: params  # arbitrary name, not used in the actual query string
    description: >-
      Parameter names must be in the format `list[n]`
      where `n` is an integer starting from 0.
    schema:
      type: object
    example:
      list[0]: x
      list[1]: y
      list[2]: z

在Swagger UI中，在JSON对象（非数组）格式中输入查询参数，例如：

{
  "list[0]": "x",
  "list[1]": "y",
  "list[2]": "z"
}

Swagger UI会将其转换为以下查询字符串（在URL编码之前）：

?list[0]=x&list[1]=y&list[2]=z

OpenAPI 3.1

OAS 3.1将我们向前迈进了一步。您仍然会使用 free-form查询方法，但使用新的 pattern> pattern> pattern> pattern properties 关键字，以指定一个针对正则表达式的关键字允许的参数名称（例如^list \ [\ d+\] $）。

# openapi: 3.1.0

parameters:
  - in: query
    name: params  # arbitrary name, not used in the actual query string
    description: >-
      Parameter names must be in the format `list[n]`
      where `n` is an integer starting from 0.
    schema:
      type: object
      patternProperties:   # <--------
        ^list\[\d+\]$:
          type: string
      additionalProperties: false
    example:
      list[0]: x
      list[1]: y
      list[2]: z