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

问题背景

在使用 Swagger UI 展示 API 文档时，开发者可能会遇到一个关于模型名称显示的特殊情况。当使用 OpenAPI 3.1 规范时，模型定义中的 title 属性有时会被忽略，转而显示模型名称（即 schema 的 key），而在 OpenAPI 3.0 规范下却能正确显示 title 属性。

现象对比

在 OpenAPI 3.0 规范中，如果为模型定义了 title 属性，Swagger UI 会优先显示这个标题。例如：

components:
  schemas:
    Pet:
      title: 我的宠物
      type: object
      properties:
        id:
          type: integer

这种情况下，UI 会显示"我的宠物"作为模型名称。

然而，在 OpenAPI 3.1 规范中，即使定义了相同的 title 属性，Swagger UI 有时会忽略它而直接显示模型名称（如"Pet"），这导致了不一致的用户体验。

技术原因

这个问题的根源在于 Swagger UI 对不同版本 OpenAPI 规范的处理逻辑存在差异。OpenAPI 3.1 规范引入了一些新的特性和变化，而 Swagger UI 的渲染逻辑没有完全同步更新，导致在某些情况下无法正确识别和显示 title 属性。

解决方案

Swagger UI 开发团队已经意识到这个问题，并在后续版本中进行了修复。修复后的版本能够正确处理 OpenAPI 3.1 规范中的 title 属性，确保与 OpenAPI 3.0 规范下的显示行为保持一致。

最佳实践

为了确保模型名称在各种环境下都能正确显示，建议开发者：

1. 始终为重要的模型定义明确的 title 属性
2. 保持 Swagger UI 版本更新，以获取最新的修复和改进
3. 在定义模型时，同时考虑名称和标题的语义清晰度

总结

Swagger UI 作为流行的 API 文档工具，其与 OpenAPI 规范的兼容性对开发者体验至关重要。这个模型名称显示问题虽然看似小，但反映了工具与规范版本间同步的重要性。通过保持工具更新和遵循最佳实践，开发者可以确保 API 文档的一致性和专业性。