Swagger生成Spring Server后int64参数加范围被识别为字符串

问题原因 #

这是Swagger Codegen生成Spring服务时的已知问题。当给int64类型参数加上minimum/maximum限制后，生成代码中的Swagger注解会出现逻辑偏差，导致Swagger UI误将参数识别为字符串。本质是Codegen在处理数值范围约束时，对Spring MVC的参数绑定逻辑处理不到位——Flask的Codegen逻辑对该场景的处理更准确，因此未出现此问题。

解决办法 #

1. 手动修正生成的Controller代码 #

找到对应接口的Controller方法，调整参数的注解与类型：

• 在@Parameter注解的schema属性中，明确指定type="integer"、format="int64"，同时保留范围限制值
• 确保参数的Java类型为Long，避免误写为String

示例修正后的代码片段：

@GetMapping("/example-api")
public ResponseEntity<ExampleResponse> getExample(
    @Parameter(description = "示例ID", required = true,
               schema = @Schema(type = "integer", format = "int64",
                               minimum = "1", maximum = "1000000"))
    @RequestParam Long id
) {
    // 业务逻辑实现
    return ResponseEntity.ok(new ExampleResponse());
}

2. 生成服务器时添加配置参数 #

在Swagger Editor生成Spring服务器时，勾选「Use Swagger Annotations」选项；若使用命令行生成，可添加参数--additional-properties useSwaggerAnnotations=true，强制生成标准的Swagger注解，避免类型映射错误。

3. 升级OpenAPI规范版本 #

确保API规范使用OpenAPI 3.0及以上版本，在规范中明确定义参数的schema结构：

parameters:
  - name: id
    in: query
    required: true
    schema:
      type: integer
      format: int64
      minimum: 1
      maximum: 1000000

高版本规范对数值类型的约束定义更清晰，能降低Codegen的解析误差。

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