OpenAPI 路径/查询参数嵌套结构序列化

如何解决OpenAPI 路径/查询参数嵌套结构序列化

在关于参数序列化的 OpenAPI 文档中，有一个简短的部分介绍了如何使用不同样式序列化查询、路径、标头和 cookie 参数。这些参数的模式被描述为 OpenAPI 风格的 json 模式，它允许对象和数组的无限嵌套。我在文档中没有发现任何关于如何处理这些问题的提及：

https://swagger.io/docs/specification/serialization/

假设为任何参数提供的 JSON 架构如下所示：

{
  "type": "object","properties": {
    "foo": {
      "type": "object","properties": {
        "bar": "string"
      }
    }
  }
}

意味着它允许 JSON 中的结构，例如：

{
  "foo": {
    "bar": "hello"
  }
}

或嵌套数组的类似概念：

{
  "type": "array","items": {
    "type": "array","items": {
      "type": "string"
    }
  }
}

允许这样的结构（至少在 JSON 中）：

[["a"],["b"]]

我的问题：

1. 根据 OpenAPI 规范，这是否允许用于路径、查询等参数？
2. 如果是，是否有任何关于如何以规范允许的不同样式序列化这些内容的文档？
3. 如果不是，官方文档中是否提到了这一点？

我之所以这么问，是因为我正在研究需要与 OpenAPI 规范兼容的工具，我想知道我在这里可以期待什么作为参数格式。我完全意识到拥有巨大的嵌套对象并尝试在 url 中序列化它们并不是最聪明的想法。但是，我对 OpenAPI 规范允许的内容感兴趣。

解决方法

简短回答：这是未定义的行为。

大多数 OpenAPI serialization styles 基于 RFC 6570，provides guidance 仅用于：

• 原始值，
• 原始数组，
• 简单的非嵌套对象（具有原始属性）。

对于其他类型的值（嵌套对象、包含数组的对象、嵌套数组、对象数组），行为未定义。

同样，OpenAPI 自己的 deepObject 样式目前仅适用于简单对象，而不适用于数组或嵌套对象。defined。以下是 OpenAPI 规范作者/维护者的一些相关评论：

顺便说一下，我们不能让 deepObject 也对数组起作用有什么原因吗？ [...]

Darrel：支持你描述的数组是我的意图。我本应该找到一些规范的实现来作为行为的指导方针，但没有解决。

Ron：如果我们最终支持分解数组表示法，则需要明确第一个索引是 0（或 1、-1 或其他）。

(source)

Ron：当我们在规范中定义 deepObject 时，我们明确选择不提及当对象中有多个级别时会发生什么，但在我们的对话中我们选择了“不支持”。

(source)

现有功能请求扩展 deepObject 以支持数组和嵌套结构：
Support deep objects for query parameters with deepObject style