2

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

4

1 回答 1

2

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'. ​</p>

(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

于 2021-05-31T22:27:10.587 回答