SpringDoc OpenAPI 中 Schema.title 属性失效问题解析

在使用 SpringDoc OpenAPI 进行 API 文档生成时，开发者可能会遇到 Schema.title 属性不生效的情况。本文将深入分析该问题的原因及解决方案。

问题现象

当开发者从 SpringDoc OpenAPI 2.6.0 版本升级到 2.8.5 版本后，发现使用 @Schema 注解的 title 属性不再在生成的 API 文档中显示。例如：

@Schema(title = "someName")
val name: String

在 2.6.0 版本中，title 属性会正常显示为字段的标题，但在 2.8.5 版本中该属性不再生效。

根本原因

这个问题的根源在于 SpringDoc OpenAPI 2.8.0 版本开始默认使用 OpenAPI 3.1 规范，而之前的版本使用的是 OpenAPI 3.0.1 规范。OpenAPI 3.1 规范在字段显示处理上与 3.0.1 有所不同，导致了 title 属性的显示差异。

解决方案

开发者有两种选择来解决这个问题：

1. 回退到 OpenAPI 3.0.1 规范
   在应用配置文件中添加以下配置：

   springdoc.api-docs.version=openapi_3_0
   

   这种方式可以保持与之前版本完全一致的行为。

2. 适应 OpenAPI 3.1 规范
   如果开发者希望使用最新的 OpenAPI 规范，可以考虑使用其他方式来描述字段，例如：

   @Schema(description = "用户姓名")
   val name: String
   

   虽然 title 属性不再显示，但 description 属性仍然有效，可以作为替代方案。

技术背景

OpenAPI 3.1 规范对 Schema 对象的处理做了一些调整，旨在更好地支持 JSON Schema。这些变化包括：

• 更严格的类型定义
• 对组合模式（allOf/anyOf/oneOf）的改进支持
• 对 $ref 引用的处理优化

虽然这些改进在长期来看是有益的，但在过渡期间可能会导致一些兼容性问题，如本例中的 title 属性显示问题。

最佳实践建议

1. 在升级 SpringDoc OpenAPI 版本时，建议先在小范围测试 API 文档的生成效果
2. 对于关键字段的描述，同时使用 title 和 description 属性以增强兼容性
3. 考虑在团队内部统一 OpenAPI 规范版本，避免因版本差异导致的文档不一致

通过理解这些技术细节，开发者可以更好地控制 API 文档的生成效果，确保文档质量不受版本升级的影响。