Swagger UI无法正确传递对象类型查询参数问题咨询

当前的OpenAPI 3.0.3定义中，/api/v2/data/thing接口的pagination是对象类型的查询参数，但Swagger UI执行请求时会将其展开为page=0&limit=100，而非后端期望的pagination[page]=0&pagination[limit]=100，导致请求无法正常工作。

解决步骤 #

• 为对象参数显式指定style和explode属性
  OpenAPI 3.x中，对象类型查询参数默认采用form样式且explode=true，这会直接拆分对象属性为平级参数。要生成嵌套格式，需设置style: form和explode: false，强制保留父键的嵌套结构。

修改后的参数定义如下：

openapi: 3.0.3
info:
  title: SampleApi
  description: Sample backend service
  version: 1.0.0
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-TOKEN
      in: header
  schemas: {}
paths:
  /api/v2/data/thing:
    get:
      tags:
        - Data
      parameters:
        - schema:
            type: string
          in: query
          name: searchText
          required: false
        - schema:
            type: object
            properties:
              page:
                type: number
                minimum: 0
              limit:
                type: number
                maximum: 100
            additionalProperties: false
          in: query
          name: pagination
          required: true
          style: form
          explode: false
      responses:
        "200":
          description: Default Response
servers: []

• 验证效果
  更新OpenAPI定义后，Swagger UI会按照pagination[page]=0&pagination[limit]=100的格式生成查询参数，与后端期望格式匹配，请求即可正常运行。

补充说明 #

• style: form指定使用表单格式传递参数
• explode: false表示不拆分对象属性为独立参数，保留父键嵌套结构

内容的提问来源于stack exchange，提问作者abhishekbutola