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

Question

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

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

并包含具有属性的对象列表 id和 value .

我的 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

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

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

对象未序列化为数组 id和 value键。

有没有办法解决这个问题？

Answer 1

从 OpenAPI 3.1 开始，这是不可能的
OpenAPI 3.0/3.1 规范目前定义了 deepObject行为 仅适用于简单对象 (具有原始属性)例如

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

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

如果您正在设计新 API(而不是描述现有 API)，请考虑在请求正文中传递对象数组。