Swagger中Long类型高数值被自动舍入的问题求助

云上老周

2026-6-23

问题分析与解决方案

问题原因

Swagger UI 前端依赖 JavaScript 处理接口返回值，而 JS 的 Number 类型是双精度浮点数，最大安全整数仅为 2^53 - 1（即 9007199254740991）。你的 checkId 数值（如 9223372036000000005）远大于这个阈值，JS 解析时会丢失精度，导致数值被舍入到最近的可表示值。而 Postman 直接展示原始 JSON 响应，不经过 JS 数值转换，因此能显示正确结果。

解决方案（保持Long类型，无需修改业务规则）

方案1：单个字段局部配置

在实体类的 checkId 字段上，通过 @Schema 注解指定 Swagger 以字符串格式展示该字段，后端仍然返回 Long 类型数值：

@Schema(description = "Unique identifier of the check", type = "string", format = "int64")
private Long checkId;

配置后，Swagger UI 会将该字段识别为字符串类型展示，避免 JS 精度丢失，同时实际接口返回的依然是 Long 类型数值，满足业务要求。

方案2：全局配置所有Long类型

如果项目中有多个 Long 类型字段需要处理，可以通过全局配置让 Swagger 对所有 int64 类型字段统一以字符串格式展示（以 SpringDoc 为例）：

@Configuration
public class SwaggerGlobalConfig {
    @Bean
    public OpenApiCustomizer longTypeAsStringCustomizer() {
        return openApi -> {
            openApi.getComponents().getSchemas().values().forEach(schema -> {
                if ("integer".equals(schema.getType()) && "int64".equals(schema.getFormat())) {
                    schema.setType("string");
                    schema.setFormat("int64");
                }
            });
        };
    }
}