首页
/ Swashbuckle.AspNetCore 中 OpenAPI 安全需求配置的演进

Swashbuckle.AspNetCore 中 OpenAPI 安全需求配置的演进

2025-06-07 10:45:39作者:秋阔奎Evelyn

在 ASP.NET Core 项目中,Swashbuckle.AspNetCore 是生成 OpenAPI (Swagger) 文档的流行库。随着 dotnet-vnext 版本的演进,OpenAPI 安全需求的配置方式发生了变化,开发者需要了解这些变化以正确配置 JWT 认证等安全方案。

传统配置方式

在早期版本中,配置 JWT Bearer 认证的安全需求通常采用以下方式:

services.AddSwaggerGen(c =>
{
    c.AddSecurityDefinition(JwtBearerDefaults.AuthenticationScheme.ToLowerInvariant(), new OpenApiSecurityScheme
    {
        Scheme = JwtBearerDefaults.AuthenticationScheme.ToLowerInvariant(),
        Description = "标准授权头使用 Bearer 方案。示例: \"bearer {token}\"",
        In = ParameterLocation.Header,
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        BearerFormat = "JWT"
    });

    c.AddSecurityRequirement(new OpenApiSecurityRequirement()
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Id = JwtBearerDefaults.AuthenticationScheme,
                    Type = ReferenceType.SecurityScheme
                }
            },
            new List<string>()
        }
    });
});

这种方式通过 Reference 属性引用之前定义的安全方案,然后将其添加到安全需求中。

dotnet-vnext 中的新配置方式

在新版本中,API 设计发生了变化,Reference 属性不再直接可用。新的配置方式更加简洁:

services.AddSwaggerGen(c =>
{
    c.AddSecurityDefinition(JwtBearerDefaults.AuthenticationScheme.ToLowerInvariant(), new OpenApiSecurityScheme
    {
        Scheme = JwtBearerDefaults.AuthenticationScheme.ToLowerInvariant(),
        Description = "标准授权头使用 Bearer 方案。示例: \"bearer {token}\"",
        In = ParameterLocation.Header,
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        BearerFormat = "JWT"
    });

    c.AddSecurityRequirement((document) => new() 
    { 
        [new(JwtBearerDefaults.AuthenticationScheme.ToLowerInvariant(), document)] = [] 
    });
});

关键变化解析

  1. 引用方式变化:不再使用 Reference 属性,而是直接在安全需求中通过方案名称引用

  2. Lambda 表达式:新的 AddSecurityRequirement 方法接受一个文档参数,允许更灵活的配置

  3. 字典初始化:使用更简洁的字典初始化语法来定义安全需求

  4. 方案标识:通过方案名称和文档实例的组合来唯一标识安全方案

实际应用建议

在实际项目中配置 JWT 认证时,建议:

  1. 保持方案名称的一致性,通常使用 JwtBearerDefaults.AuthenticationScheme 的转换形式

  2. 注意大小写敏感性,建议统一使用小写形式

  3. 对于复杂的多认证方案场景,可以为每个方案定义独立的安全需求和定义

  4. 考虑将 Swagger 配置提取到扩展方法中,提高代码可维护性

这种新的配置方式不仅简化了代码,还提供了更大的灵活性,使开发者能够更好地适应各种安全需求场景。随着 OpenAPI 规范的演进,这种变化也使得 Swashbuckle.AspNetCore 能够更好地支持未来的功能扩展。

登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起