OpenAPI3生成复杂查询API时前后端参数格式不匹配求助

问题背景 #

用OpenAPI 3定义带复杂查询对象的API，自动生成Spring Boot控制器和TypeScript客户端后，客户端请求会带filter.前缀（如filter.name=test），但服务端期望直接使用对象属性作为查询参数（如name=test），即便设置了deepObject风格也无法解决。

可行解决方案 #

方案1：修正OpenAPI参数定义（最优） #

放弃用content/application/json定义查询参数对象，改用schema直接引用，并显式指定style: form和explode: true，同时确保参数映射正确：

parameters:
  - in: query
    name: page
    schema:
      type: integer
      example: 0
  - in: query
    name: size
    schema:
      type: integer
      example: 5
  - in: query
    name: filter
    schema:
      $ref: "#/components/schemas/ComplexFilter"
    style: form
    explode: true
components:
  schemas:
    ComplexFilter:
      type: object
      properties:
        name:
          type: string
        lastname:
          type: string
        userName:
          type: string

这样生成的TypeScript客户端会将ComplexFilter的属性展开为顶级查询参数，而Spring Boot控制器无需额外修改即可正确解析。

方案2：修改Spring Boot控制器适配前缀参数 #

如果无法修改OpenAPI定义，可在控制器参数上添加@ModelAttribute注解，让Spring自动解析带filter.前缀的参数到ComplexFilter对象：

@RequestMapping(method = RequestMethod.GET, value = "/users")
@ResponseBody
public List<User> search(
    @RequestParam(value = "page") Integer page,
    @RequestParam(value = "size") Integer size,
    @ModelAttribute("filter") ComplexFilter filter
) {
    return service.filter(page, size, filter);
}

方案3：调整OpenAPI Generator客户端生成配置 #

在生成TypeScript客户端时，通过配置强制使用form风格展开参数：

• 使用命令行参数：

openapi-generator-cli generate -i openapi.yaml -g typescript-axios --additional-properties=queryParamStyle=form,queryParamExplode=true

• 或在配置文件openapi-generator-config.yml中添加：

additionalProperties:
  queryParamStyle: form
  queryParamExplode: true

关键说明 #

• 使用schema而非content定义查询参数对象是核心，content通常用于传递序列化的JSON字符串参数，而非展开的表单参数。
• style: form + explode: true是form风格参数的默认行为，但显式声明可避免生成器的默认逻辑偏差。

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