如何使用OpenAPI Generator生成含多可选查询参数的易用Java客户端

方案1：启用Lombok生成Builder（推荐） #

通过OpenAPI Generator的配置开启Lombok支持，让生成的请求记录自动带上@Builder注解，用Builder模式构建请求对象，彻底避免传大量null值。

修改你的Gradle配置，在configOptions中添加Lombok相关设置：

openApiGenerate {
  generatorName.set("java")
  configOptions.set(mapOf(
    "library" to "restclient",
    "hideGenerationTimestamp" to "true",
    "useSingleRequestParameter" to "true",
    "generateBuilders" to "true",
    "lombok" to "true", // 启用Lombok支持
    "builderPattern" to "builder" // 指定生成Builder模式
  ))
  globalProperties.set(mapOf(
    "apiDocs" to "false",
    "modelDocs" to "false",
  ))
  inputSpec.set("$rootDir/sdk/openapi.json")
}

生成后的请求记录会自动包含@Builder注解：

@Builder
public record GetSalesOrdersRequest(LocalDate startOrderDate, LocalDate endOrderDate, String customerId, String locationId, ... String branchId){}

调用时只需设置需要的参数：

salesOrderControllerApi.getSalesOrders(
    GetSalesOrdersRequest.builder()
        .endOrderDate(LocalDate.of(2025, 4, 5))
        .build()
);

注意：项目中需预先引入Lombok依赖，Gradle配置示例：

implementation 'org.projectlombok:lombok:1.18.30'
annotationProcessor 'org.projectlombok:lombok:1.18.30'

方案2：切换到支持链式Setter的库 #

若不想依赖Lombok，可切换OpenAPI Generator的Java库类型为spring-boot，它默认生成带链式Setter的POJO（而非Java Record）：

修改configOptions中的library配置：

configOptions.set(mapOf(
    "library" to "spring-boot",
    "hideGenerationTimestamp" to "true",
    "useSingleRequestParameter" to "true",
    "generateBuilders" to "true"
))

生成的请求类会自带链式Setter方法：

public class GetSalesOrdersRequest {
    private LocalDate startOrderDate;
    private LocalDate endOrderDate;
    // 其他字段

    public GetSalesOrdersRequest setEndOrderDate(LocalDate endOrderDate) {
        this.endOrderDate = endOrderDate;
        return this;
    }
    // 其他链式Setter
}

即可实现你期望的调用方式：

salesOrderControllerApi.getSalesOrders(
    new GetSalesOrdersRequest().setEndOrderDate(LocalDate.of(2025, 4, 5))
);

方案3：自定义模板（进阶） #

如果上述方案无法满足特殊需求，可自定义OpenAPI Generator的模板文件，修改请求类的生成逻辑。

1. 下载官方Java模板文件，复制到项目本地目录（如custom-templates）
2. 修改record.mustache或model.mustache模板，添加自定义Builder或链式方法的代码
3. 在Gradle配置中指定自定义模板路径：

openApiGenerate {
    // 其他配置
    templateDir.set("$rootDir/custom-templates")
}

这种方式灵活性最高，但需要维护自定义模板，适合有个性化需求的场景。

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