升级Visual Studio到16.11.1后Swagger报Failed to load API definition错误如何解决

第一步：开启Swagger详细错误定位问题根源 #

VS 16.11.1 对应的 ASP.NET Core SDK 对路由和API元数据的校验规则更严格，Swagger生成文档时只要检测到不符合规则的API就会直接抛出定义加载失败的错误。你可以先修改Swagger配置输出具体错误信息：

• 在服务注册代码（.NET 5及更早版本为Startup.cs的ConfigureServices方法，.NET 6+为Program.cs）中添加如下配置：

services.AddSwaggerGen(options =>
{
    // 保留你原有的Swagger配置
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    // 新增：解决Action冲突，优先取第一个匹配项
    options.ResolveConflictingActions(apiDesc => apiDesc.First());
});

• 在中间件配置部分添加Swagger详细错误输出：

app.UseSwagger();
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "你的API名称 v1");
    // 开启详细错误展示
    options.DisplayOperationId();
});

修改后重新运行项目，直接访问/swagger/v1/swagger.json地址，页面会输出具体的错误原因和对应的API接口信息。

第二步：处理最常见的兼容问题 #

升级Swagger相关NuGet包 #

VS 16.11.1 最低适配的Swashbuckle.AspNetCore版本为5.6.3，如果你的项目中该包版本更低，会存在兼容性问题。打开NuGet包管理器，将所有Swashbuckle.AspNetCore开头的包升级到对应.NET版本的最新稳定版即可：

• .NET 5项目升级到5.x最新稳定版
• .NET 6及以上版本升级到6.x最新稳定版

清理本地编译缓存 #

VS升级后旧的编译缓存可能会导致运行异常，手动删除项目根目录下的bin、obj文件夹，之后重新生成项目即可解决大部分兼容性问题。

第三步：排查API配置问题 #

如果上面的操作还没解决问题，按以下规则检查所有Controller的Action配置：

• 所有接口Action必须标注[HttpGet]/[HttpPost]/[HttpPut]/[HttpDelete]这类HTTP动词特性，不能存在无动词特性的公开Action
• 相同HTTP动词下不能存在完全相同的路由模板，否则会触发路由冲突
• 如果接口使用了动态路由、自定义路由约束，确保路由模板符合ASP.NET Core的路由规则

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