Swagger/OpenAPI：在查询参数中定义数组的有效方法是什么？答案

【问题标题】：Swagger/OpenAPI: What are valid ways to define arrays in query parameters?Swagger/OpenAPI：在查询参数中定义数组的有效方法是什么？
【发布时间】：2021-08-12 17:10:15
【问题描述】：

我在 Swagger 和 OpenAPI 规范中看到了多种在查询参数中定义数组的方法。以下所有示例都有效吗？还有更多有效的选项吗？

示例 1：

...
{
    "name": "example",
    "in": "query",
    "type": "array",
    "items": {
        "type": "string"
    }
}
...

示例 2：

...
{
    "name": "example",
    "in": "query",
    "type": "array",
    "items": {
        "properties": {
            "username": {
                "type": "string"
            },
            "password": {
                "type": "string"
            }
        }
    }
}
...

示例 3：

...
{
    "name": "example",
    "in": "query",
    "type": "array",
    "schema": {
        "items": {
            "type": "string"
        }
    }
}
...

示例 4：

...
{
    "name": "example",
    "in": "query",
    "type": "array",
    "schema": {
        "items": {
            "properties": {
                "username": {
                    "type": "string"
                },
                "password": {
                    "type": "string",
                }
            }
        }
    }
}
...

还有更多选择吗？

谢谢！

【问题讨论】：

标签： swagger openapi

【解决方案1】：

示例 1 和示例 3 基本相同，示例 2 和示例 4 也基本相同。不同之处在于使用的 OpenAPI 规范版本：没有schema 的示例是 OpenAPI 2.0 语法（swagger: 2.0）；使用schema - OpenAPI 3 语法 (openapi: 3.x.x)。 schema 关键字将与类型相关的关键字包装在 OpenAPI 3.0 参数定义中。

OpenAPI 2.0 和 3仅支持查询参数中的基元数组。

示例 1 是有效的 OpenAPI 2.0 参数定义。

在 OpenAPI 3 中，将使用包含 type 和 items 的 schema 定义相同的参数：

// openapi: 3.0.0

{
    "name": "example",
    "in": "query",
    "schema": {    // <--------------
      "type": "array",
      "items": {
        "type": "string"
      }
    }
}

示例 2 - 无效。这是 OpenAPI 2.0 定义，OAS 2 明确禁止查询参数中的对象数组。它只支持基元数组和数组数组。

示例 3 - 差不多，但不完全。这似乎是 OpenAPI 3，在这种情况下 type: array 必须在 schema 内，如下所示：

// openapi: 3.0.0

{
    "name": "example",
    "in": "query",
    "schema": {
      "type": "array",    // <--------------
      "items": {
        "type": "string"
      }
    }
}

示例 4 - 同样，type: array 必须在 schema 内以使此定义语法正确。然而，这个例子定义了一个对象数组，serialization behavior is not defined.所以这个例子实际上是未定义的行为。

【讨论】：

谢谢@Helen！ :)