SpringDoc OpenAPI 中 Pageable 和 Sort 对象命名异常问题分析

问题背景

在使用 SpringDoc OpenAPI 进行 API 文档生成时，开发人员发现从 2.7.0 版本升级到 2.8.0/2.8.1 版本后，生成的 OpenAPI 规范文档中出现了异常情况。具体表现为 Spring Data 的分页相关对象（Pageable 和 Sort）在生成的文档中被错误地命名为 "Pageablenull" 和 "Sortnull"，而不是预期的 "PageableObject" 和 "SortObject"。

问题现象

当开发人员在控制器方法中返回 Page<String> 类型时，生成的 OpenAPI 规范文档中出现了以下异常：

1. Pageable 对象被错误地命名为 "Pageablenull"
2. Sort 对象被错误地命名为 "Sortnull"
3. 这些错误命名的对象被其他组件引用，导致整个文档结构异常

技术分析

这个问题实际上是由于 SpringDoc OpenAPI 在处理 Spring Data 的分页类型时，类型解析逻辑出现了错误。在正常情况下，SpringDoc 应该能够正确识别 Spring Data 的核心类型（如 Page、Pageable、Sort 等），并为它们生成合理的 OpenAPI 模型定义。

在 2.8.x 版本中，类型解析过程中可能丢失了类型参数信息，导致在生成类型名称时错误地使用了 "null" 后缀。这可能是由于类型擦除或类型参数解析逻辑中的缺陷导致的。

影响范围

该问题影响以下版本：

• SpringDoc OpenAPI 2.8.0
• SpringDoc OpenAPI 2.8.1

在 2.7.0 及更早版本中，这个问题不存在，Pageable 和 Sort 对象能够被正确命名为 "PageableObject" 和 "SortObject"。

解决方案

该问题已在后续版本中得到修复。开发人员可以采取以下解决方案之一：

1. 升级到已修复该问题的 SpringDoc OpenAPI 版本
2. 如果暂时无法升级，可以回退到 2.7.0 版本
3. 实现自定义的类型名称解析器来覆盖默认行为

最佳实践建议

对于使用 Spring Data 分页功能的项目，建议：

1. 定期检查生成的 OpenAPI 文档，确保类型定义正确
2. 在升级 SpringDoc OpenAPI 版本时，特别关注分页相关类型的处理
3. 考虑为重要的 API 类型编写测试用例，验证生成的文档结构

总结

SpringDoc OpenAPI 作为 Spring Boot 项目生成 API 文档的重要工具，其稳定性对项目开发至关重要。这个 Pageable 和 Sort 对象命名异常的问题虽然不会影响实际 API 的功能，但会导致生成的文档不规范，可能影响 API 文档的使用体验。开发人员应当关注此类问题，并及时采取相应的升级或修复措施。