SpringDoc升级至2.7版本后的参数处理问题解析

在SpringBoot项目中使用SpringDoc进行API文档管理时，从SpringFox迁移到SpringDoc 2.7版本后，开发者可能会遇到两个典型问题：查询参数对象未被展开显示以及长整型数据精度丢失问题。本文将深入分析这两个问题的成因及解决方案。

查询参数对象展开问题

在SpringFox中，当控制器方法接收一个自定义对象作为查询参数时，Swagger UI会自动将该对象的属性展开为独立的查询参数。但在SpringDoc 2.7中，同样的参数会被显示为一个整体"object"类型。

这种差异源于两个库对参数处理方式的不同。SpringDoc默认将复杂对象视为单个参数，而SpringFox则采用了自动展开策略。要恢复SpringFox的行为，可以在SpringDoc配置中添加以下属性：

springdoc.default-flat-param-object=true

这个配置会强制SpringDoc将查询参数对象的所有属性平铺展开，与SpringFox的显示方式保持一致。

长整型精度丢失问题

当处理大整数时，Swagger UI的JavaScript实现会面临精度限制问题。例如，输入1917147886395588608可能会被截断为1917147886395588600。

这个问题本质上是JavaScript在处理大整数时的固有局限。JavaScript使用IEEE 754双精度浮点数表示所有数字，这导致它只能安全表示±2^53范围内的整数。对于更大的整数，精度就会丢失。

解决方案有以下几种：

1. 在DTO中使用字符串类型而非长整型来表示大整数
2. 添加@JsonSerialize(using = ToStringSerializer.class)注解，强制序列化为字符串
3. 在Swagger UI配置中明确指定数字格式

迁移建议

从SpringFox迁移到SpringDoc时，开发者需要注意以下几点：

1. 注解替换：将@ApiModelProperty替换为@Schema
2. 配置调整：根据需要设置参数展开行为
3. 数据类型处理：特别关注大整数的表示方式
4. 版本兼容性：确保SpringDoc版本与SpringBoot版本匹配

通过合理配置，SpringDoc可以提供与SpringFox相似甚至更好的API文档体验，同时获得更好的维护性和新特性支持。