Swagger/OpenAPI查询参数封装自定义模型后接收为null的问题排查

背景与需求 #

现有API当前包含3个查询参数，未来可能新增不同数据类型的参数。希望在api-doc.yaml中创建一个自定义模型（类）来封装所有查询参数，而非直接声明参数。已知可通过请求体传递参数，但因架构耦合限制，需采用封装到单一类的方案。

当前实现 #

模型定义（api-defs.yaml） #

PayloadQueryParams:
  type: object
  properties:
    workflow:
      type: string
      required: true
    timestamp:
      type: integer
      format: int64
      required : true
    createdTill:
      type: integer
      format: int64
      description: "timestamp in ms for querying scheduler service tasks"
      required : false
    page:
      type: integer
      description: "page number for scheduled tasks"
      required: false

接口引用（api-internal.yaml） #

/tasks:
    get:
      tags:
        - "internal"
      operationId: "getTask"
      parameters:
        - in: query
          name : PayloadQueryParams
          schema:
            $ref: '#/components/schemas/PayloadQueryParams'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/ResponseModel'
        "401":
          description: "Unauthorized"
          content: { }
        "403":
          description: "Forbidden"
          content: { }

通常通过Swagger Codegen生成样板接口，在控制器层实现并覆写方法。

遇到的问题 #

• Swagger Codegen生成的getTask方法虽使用PayloadQueryParams模型，但从URL传递的查询参数接收值为null；
• 移除Swagger定义，自行创建与生成的PayloadQueryParams完全一致的类并直接用于控制器时，单元测试正常，参数可正确解析；
• 因架构限制，必须通过Swagger Codegen实现该方案；
• 验证发现，即使类定义完全相同，非Swagger生成的类可正常工作，Swagger生成的类则无法接收参数。

期望解决方案 #

1. 排查YAML文件是否存在结构问题；
2. 确认OpenAPI版本是否影响（当前使用OpenAPI）；
3. 提供将查询参数转换为HashMap或MultiValueMap的替代方式。

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