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

在 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 能够更好地支持未来的功能扩展。