Swashbuckle.AspNetCore 在 .NET 9.0 中 Swagger UI 渲染问题解析

问题背景

在使用 ASP.NET Core 9.0 时，开发者发现 Swagger UI 无法正常渲染 API 文档，而是显示错误提示。这个问题主要出现在 Swashbuckle.AspNetCore 7.2.0 版本与 .NET 9.0 的组合环境中。

问题现象

当开发者访问 Swagger UI 端点时，界面无法正确显示 API 路由信息，而是呈现一个错误状态。通过对比 .NET 8.0 和 9.0 生成的 OpenAPI 规范差异，可以观察到版本号的细微变化：

• .NET 9.0 生成的 OpenAPI 版本为 3.0.4
• .NET 8.0 生成的 OpenAPI 版本为 3.0.1

技术分析

这个问题的本质在于 Swagger UI 对 OpenAPI 规范版本的严格校验。虽然 3.0.4 和 3.0.1 都属于 OpenAPI 3.0.x 系列，但 Swagger UI 的某些版本对具体的补丁版本号有特定要求。

解决方案

这个问题实际上是 Swagger UI 自身的一个已知问题，而非 Swashbuckle.AspNetCore 的缺陷。解决这个问题的方案有以下几种：

1. 降级 OpenAPI 版本号：可以手动将生成的 OpenAPI 规范中的版本号从 3.0.4 改为 3.0.1，这样 Swagger UI 能够正常渲染，但可能会伴随一些次要错误。

2. 升级 Swagger UI：等待或使用支持 OpenAPI 3.0.4 的 Swagger UI 版本。

3. 配置 Swashbuckle：通过配置 Swashbuckle 强制使用特定的 OpenAPI 版本号。

最佳实践建议

对于生产环境，建议：

• 保持 Swashbuckle.AspNetCore 和 Swagger UI 的版本同步更新
• 在升级 .NET 版本时，先进行充分的测试
• 考虑锁定 OpenAPI 规范版本以确保稳定性

总结

这个问题展示了在 API 文档工具链中各组件版本兼容性的重要性。开发者在升级 .NET 或相关工具时，应当关注这些细微但关键的版本变化，以确保文档生成功能的稳定性。