带有对象列表的OpenAPI查询字符串参数

Question

我正在尝试使用OpenAPI记录一个查询字符串，它看起来像

filtered[0][id]=code&filtered[0][value]=12345

并包含具有属性 ID 和值的对象列表。

我的 yaml 文档如下所示

parameters:
    - name: filtered
      in: query
      description: filters to be applied
      explode: true
      style: deepObject
      schema:
        type: array
        items:
          properties:
            id:
              description: name of the field to be filtered
              type: string
            value:
              description: value of the filter
          type: object

问题如下：它看起来像＜code＞样式：deepObject＜/code＞选项只适用于一个级别，而不适用于我的对象实际所在的第二个级别。也就是说，它需要一个查询字符串，如

?sorted[0]=%7B%0A%20%20%22id%22%3A%20%22string%22%2C%0A%20%20%22value%22%3A%20true%0A%7D

对象未序列化为具有id和值键的数组。

有办法解决吗？

Answer 1

我知道这是一个老问题，但是从打开 api 3 开始，就支持您正在寻找 https://swagger.io/docs/specification/describing-parameters/#schema-vs-content 的内容。

据报道，Openapi生成器6.0.1修复了一个错误https://github.com/OpenAPITools/openapi-generator/issues/4808

parameters:
  - in: query
    name: filter
    content:
      application/json:      
        schema:
          schema:
           $ref: "#/components/schemas/Filter"

Answer 2

顾名思义，:)，deepObject 样式仅“提供了一种渲染嵌套对象的简单方法”，而不是数组。至少根据版本 3.0.1，它仅适用于对象。

请注意，工具可能还不支持嵌套对象，因为规范“不提供此类示例”。

因此，您的格式与OpenAPI不兼容，但您可以将查询定义为正则表达式后面的参数。我通常会尽力提供一些解释

https://swagger.io/specification/

使现代化显然，在有人要求为嵌套对象提供“描述性错误”消息后，建议在https://github.com/swagger-api/swagger-js/pull/1450遗憾的是，决定不纳入该功能，PR 1450被拒绝。

Answer 3

从OpenAPI 3.1开始这是不可能的

OpenAPI 3.0/3.1规范目前仅为简单对象（具有原始属性）定义深度对象行为，例如

{
  "id": 5,
  "name": "Bob"
}

但不适用于数组，也不适用于嵌套对象。

由于数组和嵌套对象的行为未定义，因此实际上无法描述查询字符串。从技术上讲，唯一的方法是将 filtered[0][id]、filtered[0][value] 等定义为单独的查询参数。