OpenAPI 路径/查询参数嵌套结构序列化 [英] OpenAPI path/query parameters nested structure serialization

问题描述

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

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

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

<代码>{类型":对象"，属性":{富":{类型":对象"，属性":{条":字符串"}}}}

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

<代码>{富":{酒吧":你好"}}

或嵌套数组的类似概念:

<代码>{类型":数组"，物品":{类型":数组"，物品":{类型":字符串"；}}}

允许这样的结构(至少在 JSON 中):

[[a"], [b"]]

我的问题:

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

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

解决方案

简短回答:这是未定义的行为.

大多数 OpenAPI 序列化样式都基于 RFC 6570，其中 提供指导仅用于:

• 原始值，
• 原始数组，
• 简单的非嵌套对象(具有原始属性).

对于其他类型的值(嵌套对象、包含数组的对象、嵌套数组、对象数组)，行为未定义.

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

<块引用>

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

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

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

(来源)

<块引用>

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

(来源)

现有功能请求扩展 deepObject 以支持数组和嵌套结构:
支持 deepObject 查询参数的 deepObject 样式

In the OpenAPI docs about parameter serialization there's a short section about how to serialize query, path, header and cookie parameters with different styles. The schema of these parameters are described as OpenAPI flavoured json schema, which allows infinite nesting of objects and arrays. I haven't found any mention about how to deal with these in the docs:

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

Let's assume the JSON schema provided for any of the parameters is like this:

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

Meaning it allows structures in JSON such as:

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

Or similar concept with arrays that are nested:

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

Which allows structures like this (at least in JSON):

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

My question:

1. Is this allowed for path, query, etc parameters according to OpenAPI spec?
2. In case it is, are there any docs on how to serialize these in the different styles the spec allows?
3. In case it is not, is this mentioned anywhere in official docs?

I'm asking this because I'm working on tooling that needs to be compatible with the OpenAPI spec, and I'd like to know what can I expect here as parameter formats. I'm fully aware that having giant nested objects and trying to serialize them in a url is not the smartest idea. However I'm interested in what the OpenAPI spec allows.

解决方案

Short answer: It's undefined behavior.

Most OpenAPI serialization styles are based on RFC 6570, which provides guidance only for:

• primitive values,
• arrays of primitives,
• simple non-nested objects (with primitive properties).

In case of other types of values (nested objects, objects containing arrays, nested arrays, arrays of objects) the behavior is undefined.

Similarly, OpenAPI's own deepObject style is currently defined only for simple objects but not for arrays or nested objects. Here are some related comments from the OpenAPI Specification authors/maintainers:

By the way, is there a reason we couldn't have deepObject work for arrays too? [...]

Darrel: Supporting arrays as you describe was my intent. I was supposed to find some canonical implementation to use as a guideline for the behavior, but didn't get around to it.

Ron: If we end up supporting the exploded array notation, it needs to be clear that the first index is 0 (or 1, or -1, or whatever).

(source)

Ron: when we defined deepObject in the spec, we explicitly chose to not mention what happens when the object has several levels in it, but in our conversations we went with 'not supported'. ​

(source)

There's an existing feature request to extend deepObject to support arrays and nested structures:
Support deep objects for query parameters with deepObject style

这篇关于OpenAPI 路径/查询参数嵌套结构序列化的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！