具有对象列表的OpenAPI查询字符串参数 [英] OpenAPI query string parameter with list of objects

问题描述

我正在尝试使用 OpenAPI 类似于以下查询字符串的文档

I am trying to document with OpenAPI a query string which look like

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

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

and contains a list of object with properties id and 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选项仅适用于一个级别，而不适用于我的对象实际所在的第二个级别.也就是说，它需要一个查询字符串，例如

The problem is the following: it looks like the style: deepObject option works only for one level, and not at the second level where my objects actually are. That is, it expects a query string like

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

该对象未使用id和value键序列化为数组.

with the object not serialized as an array with id and value keys.

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

Is there a way to solve this?

推荐答案

从OpenAPI 3.0.2开始，这是不可能的.

OpenAPI 3.0规范当前仅针对简单对象(具有原始属性)定义deepObject行为，例如

OpenAPI 3.0 Specification currently defines the deepObject behavior only for simple objects (with primitive properties) such as

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

但不适用于数组和不适用于嵌套对象.

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

Since the behavior for arrays and nested objects is not defined, there's really no way to describe your query string. Technically, the only way would be to define filtered[0][id], filtered[0][value], etc. as individual query parameters.

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

If you are designing a new API (rather than describing an existing one), consider passing the array of objects in the request body instead.

这篇关于具有对象列表的OpenAPI查询字符串参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！