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（首字母大写）——它必须小写 bearer，否则 OpenAPI 规范不认。
.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()必须在UseSwaggerUI()之前，且紧挨着UseRouting()
顺序错一个位置，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 管理职责。
