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

Question

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

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

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

这现在可以通过 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 定义了多个值的分隔方式。可能的样式取决于参数位置——路径、查询、标题或 cookie。
• 爆炸 (true/false) 指定数组和对象是否应为每个数组项或对象属性生成单独的参数。

对于上面的示例，网址将是：

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

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

Answer 2

我不认为你可以在Swagger规范中使用"object"作为查询参数,因为查询参数只支持基本类型(https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data -types)