ASP.NET Core 8.0 Swagger端点无认证锁及认证选项异常问题

问题排查 #

你碰到的两个Swagger问题，本质是生成代码后Swagger配置未正确关联OpenAPI规范里的安全规则，UI端的认证筛选逻辑也没生效：

• 端点无锁形标识：本地Swagger UI没正确识别/authorize的jwt_token_auth安全要求，导致不显示认证标识，请求时也不会自动加Authentication头；
• 认证选项乱展示：点击锁形图标时，UI没按端点绑定的安全方案过滤，直接显示所有配置的认证方式。

修复方案 #

1. 手动绑定端点安全要求 #

生成的代码通常不会自动把OpenAPI里的security配置映射到Swagger文档，得在Program.cs里手动给每个端点加对应的安全要求：

builder.Services.AddSwaggerGen(c =>
{
    // 加载项目XML注释（确保路径正确）
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    c.IncludeXmlComments(xmlFilePath);

    // 注册两个安全方案
    c.AddSecurityDefinition("jwt_token_auth", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.Http,
        Scheme = "basic",
        Description = "基础认证，用于获取JWT令牌"
    });

    c.AddSecurityDefinition("student_data_auth", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
        Description = "JWT认证，用于访问学生数据接口"
    });

    // 添加自定义过滤器，给指定端点绑定安全要求
    c.OperationFilter<EndpointSecurityBindingFilter>();
});

// 自定义操作过滤器：根据端点路径绑定对应的安全方案
public class EndpointSecurityBindingFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var relativePath = context.ApiDescription.RelativePath;
        var httpMethod = context.ApiDescription.HttpMethod;

        // 给/authorize POST绑定jwt_token_auth
        if (relativePath == "authorize" && httpMethod.Equals("POST", StringComparison.OrdinalIgnoreCase))
        {
            operation.Security = new List<OpenApiSecurityRequirement>
            {
                new()
                {
                    {
                        new OpenApiSecurityScheme
                        {
                            Reference = new OpenApiReference
                            {
                                Type = ReferenceType.SecurityScheme,
                                Id = "jwt_token_auth"
                            }
                        },
                        new List<string>()
                    }
                }
            };
            return;
        }

        // 给所有student相关端点绑定student_data_auth
        if (relativePath.StartsWith("student", StringComparison.OrdinalIgnoreCase))
        {
            operation.Security = new List<OpenApiSecurityRequirement>
            {
                new()
                {
                    {
                        new OpenApiSecurityScheme
                        {
                            Reference = new OpenApiReference
                            {
                                Type = ReferenceType.SecurityScheme,
                                Id = "student_data_auth"
                            }
                        },
                        new List<string>()
                    }
                }
            };
        }
    }
}

2. 配置Swagger UI强制筛选认证选项 #

在启用Swagger UI时，添加配置让UI根据端点的安全要求自动过滤可选认证方式：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "API v1");
    c.EnableTryItOutByDefault();
    // 开启操作ID显示，帮助UI更精准识别端点
    c.DisplayOperationId();
});

3. 检查OpenAPI生成器设置 #

在IntelliJ用OpenAPI生成器时，要勾选Generate Swagger annotations或者Include security requirements选项，避免生成的代码丢失安全配置的映射关系。

验证方法 #

1. 重启API项目，打开本地Swagger UI；
2. 查看/authorize端点是否显示锁形标识，发起请求时是否自动带上Basic Auth请求头；
3. 点击GET /student的锁形图标，确认只显示student_data_auth这一个认证选项。

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