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

Question

我见过多种在 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",
                }
            }
        }
    }
}
...

还有更多选择吗？

谢谢！

Answer 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 内才能使此定义语法正确.但是，此示例定义了一个对象数组，其中。所以这个例子实际上是 undefined behavior.

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

Swagger/OpenAPI: What are valid ways to define arrays in query parameters?

swagger

openapi