SpringDoc OpenAPI 在 Spring Boot 3 升级后 Sort 属性与文档描述不一致问题解析

问题背景

在 Spring Boot 从 2.x 升级到 3.x 版本后，开发者在使用 SpringDoc OpenAPI 时发现了一个关于分页排序属性的文档与实际响应不一致的问题。具体表现为：API 实际返回的排序对象包含 empty、unsorted 和 sorted 三个布尔属性，而自动生成的 OpenAPI 文档却描述为包含 direction、nullHandling 等字段的复杂结构。

技术分析

1. 版本变更的影响

这个问题主要出现在以下环境组合中：

• Spring Boot 3.3.2
• springdoc-openapi-starter-webmvc-ui 2.6.0
• springdoc-openapi-maven-plugin 1.4

在 Spring Boot 2.x 时代，Spring Data 的分页排序对象确实会返回包含 empty、unsorted 和 sorted 三个属性的简单结构。但在升级到 Spring Boot 3.x 后，Spring Data 内部对分页和排序的实现进行了重构，导致了这种不一致现象。

2. 问题本质

问题的核心在于 SpringDoc OpenAPI 的 Schema 生成机制未能及时跟上 Spring Data 3.x 的变更。具体表现为：

• 实际响应：Sort 对象现在是一个包含状态标记（empty/unsorted/sorted）的简单对象
• 文档描述：仍然保持着旧版本中更复杂的排序对象结构，包含 direction、property 等字段

这种不一致会导致 API 消费者产生困惑，特别是那些依赖 OpenAPI 文档生成客户端代码的项目。

解决方案

根据仓库维护者的回复，这个问题将在 SpringDoc OpenAPI 的 2.7.0 版本中得到修复。对于当前遇到此问题的开发者，可以考虑以下临时解决方案：

1. 自定义 Schema：通过 @Schema 注解手动覆盖自动生成的排序对象描述
2. 等待更新：升级到即将发布的 2.7.0 版本
3. 文档说明：在 API 文档中添加备注说明实际返回结构

最佳实践建议

1. 版本兼容性检查：在升级 Spring Boot 大版本时，应同时检查相关生态组件（如 SpringDoc）的兼容性说明
2. API 契约测试：建立自动化测试来验证文档与实际响应的一致性
3. 渐进式升级：对于关键API，考虑分阶段升级，先验证核心功能再全面迁移

总结

这个案例展示了框架升级过程中可能遇到的微妙兼容性问题。作为开发者，我们需要：

• 理解底层框架变更对上层工具链的影响
• 建立完善的API契约验证机制
• 保持对生态组件更新动态的关注

随着 SpringDoc OpenAPI 2.7.0 的发布，这个问题将得到官方解决，在此之前开发者可以根据项目实际情况选择合适的临时解决方案。