在 swagger 文档中使用对象类型查询参数 [英] Use object type query param in swagger documentation

问题描述

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

I have a GET route where I would like to encode an object parameter in the url as a query string.

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

When writing the swagger documentation I basically get errors that disallow me to use schema/object types in a query type parameter:

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

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

The request query param having an object value would be encoded in an actual request.

尽管 swagger 在屏幕顶部显示错误，但对象在 swagger UI 编辑器中正确呈现，但该错误浮动在文档顶部.

Even though swagger shows an error at the top of the screen the object is rendered correctly in the swagger UI editor, however with that error floating on top of the documentation.

推荐答案

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

I don't think you can use "object" as query parameter in Swagger spec as query parameter only supports primitive type (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types)

这篇关于在 swagger 文档中使用对象类型查询参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！