SpringDoc OpenAPI 中 Sort 对象序列化问题解析

问题背景

在 Spring Boot 应用中使用 SpringDoc OpenAPI 生成 API 文档时，开发者发现 org.springframework.data.domain.Sort 类型的序列化结果与实际 API 响应不一致。这个问题主要出现在 Spring Boot 2.x 及以上版本中。

问题现象

当使用 Spring Boot 3.2.10 和 SpringDoc OpenAPI 2.6.0 时，API 文档中对于 Sort 对象的描述与实际 API 响应存在差异：

1. OpenAPI 文档描述：将 Sort 对象描述为一个包含 SortObject 元素的数组
2. 实际 API 响应：Sort 对象是一个包含 sorted、empty 和 unsorted 属性的对象

这种不一致性会导致 API 文档与真实行为不符，可能误导 API 使用者。

技术分析

Spring Data 的变化

在 Spring Boot 2.x 版本中，Spring Data 对 Sort 对象的 JSON 序列化方式进行了重大变更：

• Spring Boot 1.x：Sort 被序列化为数组形式
• Spring Boot 2.x+：Sort 被序列化为对象形式，包含三个主要属性：
  • sorted：布尔值，表示是否已排序
  • empty：布尔值，表示排序条件是否为空
  • unsorted：布尔值，表示是否未排序

SpringDoc OpenAPI 的处理

当前 SpringDoc OpenAPI 的实现仍然基于 Spring Boot 1.x 的序列化方式，没有适配 Spring Boot 2.x 及更高版本的变更。这导致了文档生成与实际行为的不匹配。

解决方案建议

要解决这个问题，可以考虑以下几种方案：

1. 自定义 Schema 处理器：实现自定义的 OpenApiCustomiser 或 SchemaPropertyCustomizer 来修正 Sort 类型的描述
2. 等待官方修复：关注 SpringDoc OpenAPI 的更新，等待官方提供对 Spring Boot 2.x+ 的完整支持
3. 使用替代方案：在 API 设计中避免直接暴露 Spring Data 的 Sort 类型，改用自定义的排序参数

最佳实践

对于正在使用 Spring Boot 2.x+ 和 SpringDoc OpenAPI 的开发者，建议：

1. 明确文档与实际行为差异，在 API 文档中添加说明
2. 考虑为排序功能设计更稳定的 API 接口
3. 定期检查 SpringDoc OpenAPI 的更新，及时升级版本

总结

Spring 生态系统的演进带来了许多改进，但同时也可能导致一些兼容性问题。作为开发者，我们需要关注这些变化，并在 API 设计和文档生成过程中做出相应调整。对于这个特定的 Sort 序列化问题，理解其背后的技术背景有助于我们做出更合理的技术决策。