OpenAPI 3.1生成Spring控制器：endDate类型与默认值配置问题

问题背景 #

开发Spring REST服务时，通过OpenAPI Generator生成控制器，需要实现日期区间搜索，要求endDate参数默认值为当前时间LocalDateTime.now()，但遇到两难情况：

• 将endDate的format设为date-time时，生成器会忽略默认值配置，不会在@RequestParam中生成defaultValue属性
• 将format设为string时，虽然能保留默认值，但参数类型会变成String，不符合业务要求

现有OpenAPI规范片段 #

schema:
            default: 50
            type: integer
            description: 最多返回的条目数量
        - in: query  # 注：原代码中`in: item`应为笔误，实际请求参数位置应为query
          name: startDate
          schema:
            type: string
            format: date
          description: 搜索条目的起始日期
        - in: query
          name: endDate
          schema:
            type: string
            format: string
            default: "#{T(java.time.LocalDateTime).now()}"     
          description: 搜索条目的结束日期

使用的生成命令 #

java -jar openapi-generator-cli.jar generate -i item.yaml -g spring --additional-properties delegatePattern=true --skip-validate-spec

当前生成的控制器方法 #

default ResponseEntity<List<Item>> itemsGet(

        @Parameter(name = "limit", description = "最多返回的条目数量", in = ParameterIn.QUERY) @Valid @RequestParam(value = "limit", required = false, defaultValue = "50") Integer limit,

        @Parameter(name = "startDate", description = "搜索条目的起始日期", in = ParameterIn.QUERY) @Valid @RequestParam(value = "startDate", required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,

        @Parameter(name = "endDate", description = "搜索条目的结束日期", in = ParameterIn.QUERY) @Valid @RequestParam(value = "endDate", required = false, defaultValue = "#{T(java.time.LocalDateTime).now()}") String endDate

    ) {

        return getDelegate().itemsGet(limit, startDate, endDate);
    }

期望生成的控制器方法 #

default ResponseEntity<List<Item>> itemsGet(

        @Parameter(name = "limit", description = "最多返回的条目数量", in = ParameterIn.QUERY) @Valid @RequestParam(value = "limit", required = false, defaultValue = "50") Integer limit,

        @Parameter(name = "startDate", description = "搜索条目的起始日期", in = ParameterIn.QUERY) @Valid @RequestParam(value = "startDate", required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,

        @Parameter(name = "endDate", description = "搜索条目的结束日期", in = ParameterIn.QUERY) @Valid @RequestParam(value = "endDate", required = false, defaultValue = "#{T(java.time.LocalDateTime).now()}") LocalDateTime endDate

    ) {

        return getDelegate().itemsGet(limit, startDate, endDate);
    }

可行解决方案 #

方案1：自定义生成器模板（推荐） #

修改Spring生成器的api.mustache模板，确保date-time类型参数保留默认值生成逻辑：

• 执行openapi-generator-cli config-help -g spring查看模板路径，复制api.mustache到本地自定义目录
• 修改模板中处理defaultValue的代码块，当参数类型为LocalDateTime时，强制生成defaultValue属性
• 生成命令中添加--template-dir <你的自定义模板目录>参数

方案2：生成后手动调整（临时方案） #

若不想修改模板，可在生成代码后手动修改参数：
将endDate的String类型改为LocalDateTime，并添加日期格式化注解：

@Valid @RequestParam(value = "endDate", required = false, defaultValue = "#{T(java.time.LocalDateTime).now()}") 
@DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)
LocalDateTime endDate

方案3：使用OpenAPI扩展属性 #

在OpenAPI规范中添加x-java-type扩展强制指定类型，同时保留date-time格式和默认值：

- in: query
          name: endDate
          schema:
            type: string
            format: date-time
            default: "#{T(java.time.LocalDateTime).now()}"
            x-java-type: java.time.LocalDateTime
          description: 搜索条目的结束日期

生成命令中添加--additional-properties useSpringBoot3=true（针对Spring Boot 3环境），部分版本的生成器会支持该扩展并保留默认值配置

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