C#怎么实现Swagger认证配置 C#如何在Swagger UI中添加JWT Bearer Token认证输入框【框架】

其实，Swagger UI 上不显示 Authorization 按钮，根本原因就是配置没到位。具体来说，需要在 AddSwaggerGen 中同时配置 AddSecurityDefinition（注意 scheme 必须小写 bearer）和 AddSecurityRequirement。另外，认证中间件 UseAuthentication 和 UseAuthorization 必须放在 UseSwaggerUI 之前，控制器上还要加上 [Authorize] 特性，这样 Swagger 才能正确识别并显示按钮。下面逐一拆解这些常见问题。

Swagger UI 里没出现 Authorization 按钮，Authorize 按钮不显示

为什么按钮没出现？说白了，就是 Swagger 文档生成时没注册 JWT Bearer 方案。Swashbuckle 不会自动猜你用了 JWT，必须显式声明 AddSecurityDefinition 和 AddSecurityRequirement。

具体操作时，在 Program.cs（.NET 6+）中配置两处：

• 在 builder.Services.AddEndpointsApiExplorer() 之后，调用 AddSwaggerGen 时传入配置委托。
• 必须同时定义 SecurityScheme：类型选 SecuritySchemeType.Http，scheme 设为 bearer（注意是小写），bearerFormat 建议设为 JWT。
• 还要在每个 API 描述里注入 SecurityRequirement，否则按钮只显示、不生效。

漏掉任意一个环节，Authorize 按钮都不会出现。最常见的错误是只加了 scheme 却忘了 AddSecurityRequirement，或者把 scheme 写成了大写开头的 Bearer——OpenAPI 规范只认小写 bearer，差一点都不行。

.NET 6+ Program.cs 中 JWT 认证配置顺序错乱导致 401 或文档不加载

配置顺序是个容易出错的细节。Swagger 要求认证中间件、授权策略和文档生成三者顺序严格对齐。最常踩的坑是：在 app.UseSwaggerUI() 前没调用 app.UseAuthentication() 和 app.UseAuthorization()，或者反过来把 AddJwtBearer 放在了 AddSwaggerGen 后面。

正确的顺序是：

• AddAuthentication().AddJwtBearer() → 先注册认证方案。
• AddAuthorization() → 再注册默认策略（比如 options.DefaultPolicy = new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build();）。
• AddEndpointsApiExplorer() + AddSwaggerGen() → 此时才能引用前面定义的 scheme 名。
• UseAuthentication() 和 UseAuthorization() 必须紧挨着 UseRouting()，并且放在 UseSwaggerUI() 之前。

顺序错一个位置，Swagger 页面可能出现空白，控制台报 Failed to load API definition，或者点击 Authorize 后调用接口仍然返回 401——实际原因是请求根本没进入认证中间件。

点击 Authorize 输入 token 后，所有接口仍带空 Authorization 头

这个问题其实在前端，不是后端配置失败。Swagger UI 默认不会自动把 token 注入到每个请求头，除非你明确告诉它哪些接口需要认证。

所以，必须在控制器或方法上加 [Authorize] 特性，并确保 Swashbuckle 能识别这个标记。关键是在 AddSwaggerGen 配置中，要启用 DocInclusionPredicate 并正确处理 AuthorizeAttribute，否则即使加了特性，Swagger 也不会给对应接口添加 security 字段。

推荐做法是在 AddSwaggerGen 委托中加入以下配置：

options.AddSecurityRequirement(new OpenApiSecurityRequirement{    {        new OpenApiSecurityScheme        {            Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" }        },        new string[] { }    }});

注意，这里的 Id = "Bearer" 必须和前面 AddSecurityDefinition("Bearer", ...) 的第一个参数完全一致，大小写敏感，否则关联断裂，token 就不会被带上。

Swagger UI 发送请求时 token 被截断或含换行，导致 401

这种情况挺常见的。用户手动粘贴 token 到弹窗时，容易带进一些不可见字符，比如从某些 JWT 网站复制时附带的 \r\n。Swagger UI 不会自动清洗，直接拼进 Authorization: Bearer xxx 头里，后端 JwtBearerHandler 解析自然失败。

这不算代码 bug，但很影响调试效率。建议：

• 在开发环境加个简单日志：在 Program.cs 的 AddJwtBearer 配置里，设置 Events.OnAuthenticationFailed 打印原始 token 长度和前 20 个字符，快速判断是否截断。
• 提醒测试人员粘贴后手动删掉首尾空格，或者用 Base64 解码工具验证 token 是否合法。
• 不推荐在生产环境绕过校验，但开发阶段可以临时加 TokenValidationParameters.ValidateLifetime = false 排除过期干扰。

真正上线时，前端应该通过登录接口获取 token 后存入内存变量，由 Axios 或 Fetch 自动注入 header。Swagger UI 只是调试工具，不该承担 token 管理职责。