如何自定义ASP.NET Swagger UI（Swashbuckle.AspNetCore.SwaggerGen）以实现自动获取用户凭证并请求授权令牌

当然可以实现这种自动获取令牌的Swagger UI！我之前在ASP.NET 6 Web API项目里配置过一模一样的功能，接下来一步步教你怎么做：

首先，确保你已经安装了必要的NuGet包——除了Swashbuckle.AspNetCore.SwaggerGen，还要Swashbuckle.AspNetCore.SwaggerUI，如果还没装的话，用NuGet包管理器或者命令行安装就行。

第一步：配置SwaggerGen的安全定义和全局授权要求 #

在Program.cs里，找到配置SwaggerGen的代码块，添加OAuth2的安全定义，同时给所有API接口加上授权要求：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });

    // 定义OAuth2安全方案
    c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.OAuth2,
        Flows = new OpenApiOAuthFlows
        {
            // 这里以**资源所有者密码凭证流程（Password Flow）**为例，适合后端API测试
            Password = new OpenApiOAuthFlow
            {
                TokenUrl = new Uri("https://你的授权服务器地址/token"), // 替换成实际的令牌端点
                Scopes = new Dictionary<string, string>
                {
                    { "api.read", "API只读权限" },
                    { "api.write", "API读写权限" }
                }
            }
            // 如果用**授权码流程（Authorization Code Flow）**，替换成下面的配置：
            // AuthorizationCode = new OpenApiOAuthFlow
            // {
            //     AuthorizationUrl = new Uri("https://你的授权服务器地址/authorize"),
            //     TokenUrl = new Uri("https://你的授权服务器地址/token"),
            //     Scopes = new Dictionary<string, string>
            //     {
            //         { "api.read", "API只读权限" },
            //         { "api.write", "API读写权限" }
            //     }
            // }
        }
    });

    // 全局添加授权要求，让所有API接口默认显示需要授权
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "oauth2"
                }
            },
            new List<string> { "api.read", "api.write" }
        }
    });
});

第二步：配置SwaggerUI的OAuth2参数 #

接下来配置SwaggerUI，让它支持OAuth2授权流程，自动获取并携带令牌：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "你的API名称 V1");
    c.RoutePrefix = string.Empty; // 可选，让Swagger UI直接在根路径访问（比如https://localhost:5001/）

    // 配置OAuth2相关参数
    c.OAuthClientId("你的客户端ID"); // 替换成授权服务器上注册的客户端ID
    c.OAuthClientSecret("你的客户端密钥"); // 替换成授权服务器上注册的客户端密钥（机密客户端需要）
    c.OAuthAppName("Swagger API测试"); // 授权弹窗显示的应用名称
    c.OAuthScopeSeparator(" "); // 作用域分隔符，默认空格即可
    c.OAuthUseBasicAuthenticationWithAccessCodeGrant(); // 如果授权服务器要求客户端用Basic Auth发送凭证，启用这个
});

几个关键注意事项 #

• 要根据你的授权服务器支持的OAuth2流程选择对应的配置（Password流程适合内部测试，Authorization Code流程更安全，适合公开场景）
• 确保TokenUrl/AuthorizationUrl是授权服务器的有效端点，客户端ID和密钥和授权服务器上的配置完全一致
• 如果用Password流程，Swagger UI的授权弹窗会显示用户名、密码输入框；如果用Authorization Code流程，会跳转到授权服务器的登录页面，登录后自动获取令牌
• 配置完成后，启动项目打开Swagger UI，就能看到右上角的Authorize按钮，点击后输入凭证，Swagger会自动获取令牌并在后续API请求的Header里带上Bearer {token}

这样就能实现你想要的自动授权令牌功能啦！

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