Visual Studio发布.NET 3.1 WebApp到Azure更新API失败如何解决？

算力阿峰

2026-10-4

问题根因与解决方案

1. Swashbuckle.AspNetCore版本适配问题

.NET 3.1 仅在Swashbuckle.AspNetCore 5.x及以上版本支持OpenApiSecurityScheme类，若你使用的是4.x及更早版本，该配置不会被正确序列化到swagger.json中，需要先升级包到.NET 3.1兼容的最新稳定版：
```
Install-Package Swashbuckle.AspNetCore -Version 5.6.3
```

2. 安全定义配置存在遗漏项

你在AddSwaggerGen中配置的OpenApiSecurityScheme必须显式声明Type属性，多数此类问题都是误将Scheme属性当Type配置导致的，正确配置示例如下：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyApi", Version = "v1" });
    
    // JWT安全定义完整配置
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.Http, // 必选项，缺失就会触发你遇到的报错
        Scheme = "bearer",
        BearerFormat = "JWT",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Description = "JWT Authorization header using the Bearer scheme."
    });
    
    // 可选：全局绑定安全要求
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" }
            },
            new string[] {}
        }
    });
});

3. 发布时Swagger生成逻辑未触发

检查项目Configure方法中是否限制了Swagger中间件仅在开发环境生效，若有该限制，发布到Azure生产环境时不会生成最新的swagger.json，会沿用旧的错误版本，可临时放开环境限制验证：
```
// 原限制写法
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

// 临时放开验证，确认问题后可按需调整访问权限
app.UseSwagger();
app.UseSwaggerUI();
```