Swagger UI 中 OpenAPI 3.1 规范下模型标题显示问题解析

在 API 文档工具 Swagger UI 的使用过程中，开发者发现了一个关于模型标题显示的兼容性问题。这个问题主要出现在 OpenAPI 3.1 规范与 3.0 规范之间的显示差异上。

当开发者在 OpenAPI 规范中为数据模型定义标题(title)属性时，Swagger UI 在不同版本规范下的渲染行为不一致。具体表现为：

1. 在 OpenAPI 3.0 规范下，Swagger UI 能够正确显示模型中定义的标题(title)属性
2. 在 OpenAPI 3.1 规范下，Swagger UI 却显示模型的名称(name)而非标题

这种不一致性会给开发者带来困惑，特别是当项目需要从 OpenAPI 3.0 升级到 3.1 时，文档的显示效果会发生变化。

从技术实现角度来看，这个问题源于 Swagger UI 对不同版本 OpenAPI 规范的解析逻辑存在差异。OpenAPI 3.1 规范引入了一些新的特性，但相应的显示逻辑没有完全同步更新。

对于开发者而言，这个问题的解决方案已经由 Swagger UI 团队通过代码修复实现。修复后的版本能够确保在不同 OpenAPI 规范版本下都优先显示模型的标题属性，保持一致的文档展示效果。

这类问题的出现也提醒我们，在使用 API 文档工具时需要注意：

1. 规范版本的选择会影响文档的最终呈现效果
2. 升级规范版本时需要进行全面的视觉回归测试
3. 工具对不同规范版本的支持可能存在细微差异

作为最佳实践，建议开发者在定义 API 文档时：

• 明确指定使用的 OpenAPI 规范版本
• 对关键模型同时定义名称和标题属性
• 定期更新文档工具以确保获得最新的兼容性修复