如何用habarta-typescript-generator生成Spring请求参数对象

原因分析 #

Spring默认不会将未标注注解的Get请求参数对象解析为查询参数，对应的代码生成工具（如OpenAPI Generator）也无法识别该对象作为查询参数集合，因此生成的客户端代码中缺失了queryParams参数。

解决方案 #

1. 使用@ParameterObject注解（推荐，Spring Boot 2.2+支持） #

给请求参数对象添加@ParameterObject注解，该注解会告诉Spring将对象的所有字段解析为查询参数，同时让代码生成工具识别到这是一组查询参数的封装。

示例代码：

// 端点定义
@GetMapping("/foo")
fun foo(@ParameterObject req: RequestDTO): String {
    // 业务逻辑实现
    return "处理完成"
}

// 请求参数DTO
data class RequestDTO(
    val page: Int?,
    val pageSize: Int?,
    val keyword: String?
    // 其他查询参数字段
)

如果需要更清晰的API文档，可以给DTO字段添加@Schema注解补充描述：

import io.swagger.v3.oas.annotations.media.Schema

data class RequestDTO(
    @Schema(description = "当前页码")
    val page: Int?,
    @Schema(description = "每页数据量")
    val pageSize: Int?,
    @Schema(description = "搜索关键词")
    val keyword: String?
)

2. 兼容老版本Spring（无@ParameterObject时） #

如果使用的Spring版本低于2.2，可以给参数对象添加@ModelAttribute注解，同样能让Spring将其解析为查询参数集合：

@GetMapping("/foo")
fun foo(@ModelAttribute req: RequestDTO): String {
    // 业务逻辑实现
    return "处理完成"
}

3. 验证代码生成结果 #

添加注解后，重新生成客户端代码，应该会得到符合预期的结构：

foo(queryParams: RequestDTO, options?: any): RestResponse<string>

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