OpenAPI中deepObject与explode查询参数未生成预期URL的问题排查

你配置的OpenAPI定义中，style: deepObject和explode: true的位置错误，导致无法生成预期的foo[bar]=baz格式查询参数。

错误原因 #

根据OpenAPI 3.x规范，style和explode是参数对象的直接属性，用于指定查询参数的序列化方式，而非嵌套在schema内部。你当前的配置把这两个属性放在了schema里，导致序列化规则未被正确识别，最终只输出了对象内部的bar=baz。

修正后的配置 #

openapi: 3.0.3
info:
  title: OpenAPI definition
  version: 0.0.1
paths:
  /example:
    get:
      parameters:
        - name: foo
          in: query
          required: false
          style: deepObject
          explode: true
          schema:
            type: object
            minProperties: 1
            example: >
              {
                "bar": "baz"
              }
      responses:
        "200":
          description: OK
        "400":
          description: Bad request
        "401":
          description: Authorization info missing or invalid
        "403":
          description: Unauthorized
        "404":
          description: Not found

说明 #

将style和explode移到参数层级后，OpenAPI工具会正确应用deepObject序列化规则，生成包含父参数名的foo[bar]=baz格式URL。

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