Springdoc OpenAPI 与 Spring Data REST 在 OpenAPI 3.1 下的兼容性问题解析

问题背景

Springdoc OpenAPI 是一个流行的库，用于为 Spring Boot 应用程序自动生成 OpenAPI 文档。当与 Spring Data REST 结合使用时，它能够自动为数据仓库接口生成 API 文档。然而，在升级到 OpenAPI 3.1 规范时，开发者遇到了类型转换异常问题。

核心问题分析

在 OpenAPI 3.1 规范下，Springdoc OpenAPI 在处理 Spring Data REST 的响应模型时会出现 ClassCastException。具体表现为：

1. 尝试将 JsonSchema 强制转换为 ObjectSchema 失败
2. 随后尝试将 JsonSchema 强制转换为 ArraySchema 也失败

这种类型转换异常的根本原因在于 OpenAPI 3.1 规范对 Schema 对象的处理方式发生了变化，而 Springdoc 的现有代码仍基于 OpenAPI 3.0 的实现假设。

技术细节

在 Springdoc 的 SpringDocDataRestUtils 类中，有以下关键代码段：

// 问题代码片段
ObjectSchema objectSchema = (ObjectSchema) entry.getValue().getProperties().get(entityClassName);
ArraySchema arraySchema = (ArraySchema) entry.getValue().getProperties().get(entityClassName);

在 OpenAPI 3.1 中，这些属性返回的是更通用的 JsonSchema 类型，而非具体的 ObjectSchema 或 ArraySchema 子类。

解决方案

目前有两种可行的解决方案：

临时解决方案

在 application.properties 或 application.yml 中显式指定使用 OpenAPI 3.0 规范：

springdoc.api-docs.version=openapi_3_0

长期解决方案

需要对 Springdoc OpenAPI 的源代码进行修改，将类型转换改为更通用的 Schema 接口：

// 建议修改后的代码
Schema<?> schema = entry.getValue().getProperties().get(entityClassName);

这样修改后，代码将同时兼容 OpenAPI 3.0 和 3.1 规范。

影响范围

此问题影响以下使用场景：

• 使用 Spring Data REST 的项目
• 配置了 OpenAPI 3.1 规范
• 使用 Springdoc OpenAPI 2.8.0 及以上版本

最佳实践建议

1. 如果项目必须使用 OpenAPI 3.1 规范，建议等待官方修复此问题
2. 对于生产环境，目前建议暂时使用 OpenAPI 3.0 规范
3. 关注 Springdoc OpenAPI 的版本更新，及时获取修复

总结

Springdoc OpenAPI 与 Spring Data REST 在 OpenAPI 3.1 下的兼容性问题主要源于规范变更导致的类型系统不匹配。开发者可以通过降级到 OpenAPI 3.0 或等待官方修复来解决这个问题。理解这一问题的本质有助于开发者更好地处理类似的技术迁移挑战。