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.0规范当前仅针对简单对象（具有原始属性）定义了deepObject行为，例如

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

但是not for arrays和not for nested objects。

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

Answer 2

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

请注意，即使嵌套对象也可能尚未得到工具的良好支持，因为规范“未提供此类示例”。

因此，您的格式与Open API不兼容，但是您可以将查询定义为遵循正则表达式的参数。在这种情况下，通常我会尽力而为地提供一些详细的解释（当然，程序员通常会跳过这些解释）

https://swagger.io/specification/

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

2 个答案: