ASP.NET Core 8.0 Web API Swagger加载失败：OpenAPI版本异常求助

问题现象 #

启动ASP.NET Core 8.0 Web API应用时，Swagger页面报错：

无法渲染该定义，提供的定义未指定有效的版本字段。请指明有效的Swagger或OpenAPI版本字段，支持的版本字段为swagger: "2.0" 以及符合openapi: 3.x.y格式的版本（例如openapi: 3.1.0）。

但直接访问https://localhost:44300/swagger/v2/swagger.json时，返回的JSON中明确包含"openapi": "3.0.4"字段，且API信息完整。

相关代码配置涉及WebApiServiceRegistration、SwaggerDocumentFilter、Program.cs，同时需结合使用的NuGet包列表排查。

排查及解决方法 #

• 检查SwaggerUI端点配置
  确认Program.cs中SwaggerUI的端点路径是否与实际swagger.json路径完全匹配，避免路由错误导致加载无效文档：

  app.UseSwaggerUI(options =>
  {
      options.SwaggerEndpoint("/swagger/v2/swagger.json", "API V2");
      // 确保此处路径和swagger.json的实际访问路径一致
  });
  

• 验证自定义DocumentFilter逻辑
  检查SwaggerDocumentFilter的Apply方法，确认未意外修改或移除根节点的openapi版本字段，避免处理文档时丢失关键版本信息。

• 清理缓存

  • 用Ctrl+Shift+R强制刷新浏览器，清除旧的文档缓存；
  • 重启应用，确保生成的swagger.json为最新版本。

• 核对NuGet包兼容性
  确保Swashbuckle.AspNetCore系列包（包括Swagger、SwaggerUI等）的版本与ASP.NET Core 8.0兼容，建议使用最新稳定版，避免版本不匹配引发解析异常。

• 排查多版本API配置冲突
  若配置了多个API版本，确认每个版本的Swagger文档都正确生成版本字段，且SwaggerUI中每个端点都对应正确的版本文档路径，避免交叉引用错误。

内容的提问来源于stack exchange，提问作者Gbenga