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

Question

在关于参数序列化的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规范允许的内容感兴趣。

Answer 1

OpenAPI spec 3.0/3.1支持JSON格式的参数序列化。它只是在你提到的那一页的末尾提到了。

< li >其他序列化方法 < li >架构与内容

来自OpenAPI规范3.0.3：

对于更复杂的情况，< code>content属性可以定义参数的媒体类型和架构。参数必须包含< code>schema属性或< code>content属性，但不能同时包含两者。

下面的OpenAPI片段显示了如何定义在问题中具有所需结构的查询参数:

  parameters:
    - name: objParam
      in: query
      content:
        application/json:
          schema:
            type: object
            properties:
              foo:
                type: object
                properties:
                  bar:
                    type: string
    - name: nestedArray
      in: query
      content:
        application/json:
          schema:
            type: array
            items:
              type: array
              items:
                type: string

Answer 2

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

大多数OpenAPI序列化样式都基于RFC 6570，它只为以下方面提供指导:

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

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

类似地，OpenAPI自己的深度对象样式目前仅针对简单对象定义，而不针对数组或嵌套对象定义。以下是OpenAPI规范作者/维护者的一些相关评论：

顺便问一下，我们不能让＜code＞deepObject＜/code＞也用于数组有什么原因吗？[...]

达雷尔：按照你的描述支持数组是我的意图。我应该找到一些规范的实现来用作行为的指导方针，但没有抽出时间。

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

（来源）

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

（来源）

有一个现有的功能请求来扩展 deepObject 以支持数组和嵌套结构：
支持具有 deepObject 样式的查询参数的深层对象