如何在ASP.NET Core 6 API Swagger UI中显示端点所需JWT令牌角色

不需要引入第三方Nuget包，直接用Swashbuckle自带的操作过滤器就能实现，核心逻辑是自动扫描控制器、接口上的授权特性，提取角色信息后追加到Swagger的接口描述中。

步骤1：编写自定义操作过滤器 #

新建类实现IOperationFilter接口，逻辑是抓取接口上的[Authorize]、[AllowAnonymous]特性，提取允许访问的角色列表，拼接成权限说明展示在接口详情里，同时自动补充401、403的响应说明，和Swagger自带的JWT授权调试功能联动。

using Microsoft.AspNetCore.Authorization;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Linq;
using System.Text;

public class AuthRolesOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 收集控制器和接口方法上的所有Authorize特性
        var authAttributes = context.MethodInfo.DeclaringType!
            .GetCustomAttributes(true)
            .Union(context.MethodInfo.GetCustomAttributes(true))
            .OfType<AuthorizeAttribute>()
            .ToList();

        // 存在AllowAnonymous特性的公开接口直接跳过
        var hasAllowAnonymous = context.MethodInfo.GetCustomAttributes(true)
            .OfType<AllowAnonymousAttribute>().Any()
            || context.MethodInfo.DeclaringType.GetCustomAttributes(true)
            .OfType<AllowAnonymousAttribute>().Any();
        if (hasAllowAnonymous || !authAttributes.Any()) return;

        // 提取、去重所有配置的允许角色
        var allowedRoles = authAttributes
            .Where(attr => !string.IsNullOrWhiteSpace(attr.Roles))
            .SelectMany(attr => attr.Roles.Split(',', StringSplitOptions.RemoveEmptyEntries))
            .Select(role => role.Trim())
            .Distinct()
            .ToList();

        // 拼接权限说明文本
        var descBuilder = new StringBuilder();
        descBuilder.AppendLine("### 🔐 访问权限要求");
        descBuilder.AppendLine("- 认证方式：JWT Bearer Token");
        if (allowedRoles.Any())
        {
            descBuilder.AppendLine($"- 允许访问角色：`{string.Join("`, `", allowedRoles)}`");
        }
        else
        {
            descBuilder.AppendLine("- 角色要求：所有已完成认证的登录用户均可访问");
        }

        // 把权限说明追加到原有接口描述的最前面，不覆盖自定义的接口注释
        operation.Description = descBuilder.ToString() + operation.Description;

        // 自动补充未授权、权限不足的响应状态码说明
        operation.Responses.TryAdd("401", new OpenApiResponse { Description = "请求未授权，缺少或存在无效JWT Token" });
        operation.Responses.TryAdd("403", new OpenApiResponse { Description = "请求已认证，但当前账号角色无访问权限" });

        // 给接口加锁标识，关联Swagger的JWT认证配置
        var bearerScheme = new OpenApiSecurityScheme
        {
            Reference = new OpenApiReference
            {
                Type = ReferenceType.SecurityScheme,
                Id = "Bearer"
            }
        };
        operation.Security = new List<OpenApiSecurityRequirement>
        {
            new OpenApiSecurityRequirement { [bearerScheme] = Array.Empty<string>() }
        };
    }
}

步骤2：注册过滤器到Swagger配置 #

找到项目里的Swagger服务注册段，.NET 6+在Program.cs，.NET 5在Startup.cs的ConfigureServices方法里，注册刚才写的过滤器，同时配置JWT安全定义，让Swagger页面支持直接输入Token调试接口。

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API项目名称", Version = "v1" });
    
    // 注册角色展示过滤器
    options.OperationFilter<AuthRolesOperationFilter>();

    // 配置JWT授权输入框
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        Scheme = "Bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header,
        Description = "输入JWT Token完成授权，格式：Bearer {你的Token值}"
    });
});

效果说明 #

• 所有标记[Authorize]的接口，会在描述区最顶部固定显示权限要求
• 配置了[Authorize(Roles = "Admin,Editor")]的接口，会清晰列出所有允许访问的角色
• 仅标记[Authorize]未指定角色的接口，会提示所有已登录用户可访问
• 标记[AllowAnonymous]的公开接口不会显示权限相关提示
• 不会覆盖你通过XML注释写的接口业务说明，只是在前面追加权限内容

适配注意点 #

• 如果你是用自定义授权策略实现角色控制，没有把角色写在[Authorize]的Roles属性上，需要在过滤器里额外注入IAuthorizationPolicyProvider读取策略配置，提取其中的角色要求即可
• 代码里做了角色去重处理，就算控制器和接口方法上都配置了角色，不会出现重复展示的问题

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