在 swagger 文档中使用对象类型查询参数

Question

我有一个 GET 路由，我想在其中将 url 中的对象参数编码为查询字符串。

在编写 swagger 文档时，我基本上会遇到不允许我在 query 类型参数中使用 schema/object 类型的错误：

paths:
  /mypath/:
    get:
      parameters
        - in: path
          name: someParam
          description: some param that works
          required: true
          type: string
          format: timeuuid #good param, works well
        - $ref: "#/parameters/mySortingParam" #this yields an error

parameters:
  mySortingParam
    name: paging
    in: query
    description: Holds various paging attributes
    required: false
    schema:
      type: object
      properties:
        pageSize:
          type: number
        cursor:
          type: object
          properties:
            after:
              type: string
              format: string

具有对象值的请求查询参数将在实际请求中进行编码。

即使 swagger 在屏幕顶部显示错误，对象在 swagger UI 编辑器中正确呈现，但是该错误浮在文档顶部。

Answer 1

我认为您不能在 Swagger 规范中使用 "object" 作为查询参数，因为查询参数仅支持原始类型 (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types)

Answer 2

这是可能的，只是 OpenAPI 2.0 不行。 OpenAPI 3.0 在此处描述了这是如何实现的：

https://swagger.io/docs/specification/describing-parameters/

parameters:
- in: query
  name: filter
  # Wrap 'schema' into 'content.<media-type>'
  content:
    application/json:  # <---- media type indicates how to serialize / deserialize the parameter content
      schema:
        type: object
        properties:
          type:
            type: string
          color:
            type: string

在此期间，您可以将查询参数作为普通的旧字符串类型，然后手动执行序列化，然后根据需要设置查询参数。这就是我在做的事情，直到 Swagger UI 完全支持 OpenAPI 3.0。

Answer 3

OpenAPI 3.0 现在可以做到这一点。

parameters:
  - in: query
    name: values
    schema:
      type: object
      properties:
        genre_id: 
          type: integer
        author_id:
          type: integer
        title:
          type: string
      example:
       {
         "genre_id": 1,
         "author_id": 1
       }
    style: form
    explode: true

在这里您可以使用 style 和 explode 关键字来指定参数的序列化方式。

style 定义如何分隔多个值。可能的样式取决于参数位置——路径、查询、header 或 cookie.
explode (true/false) 指定数组和 objects 是否应该为每个数组项或 object 属性.

对于上面的示例，url 将是：

https://ebookstore.build/v1/users/books/search?genre_id=1&author_id=1

有关使用 OpenAPI v3 描述参数和参数序列化的更多信息，请参阅 here。

在 swagger 文档中使用对象类型查询参数

Use object type query param in swagger documentation

query-parameters

swagger

swagger-ui