Swagger UI 中文注释不显示需检查XML生成路径与IncludeXmlComments一致性；Authorization按钮缺失主因是AddSecurityDefinition与AddSecurityRequirement未成对配置或scheme大小写错误（必须小写bearer）；接口需标记[Authorize]才能触发安全要求。
Swagger UI 里不显示中文注释、没 Authorization 按钮，不是配置漏了，就是关键参数写错了——尤其是 scheme 必须小写 bearer，大小写错一个字母，按钮就彻底消失。
XML 注释不显示？检查生成路径和 IncludeXmlComments 调用
XML 注释文件得真生成出来，且路径要和 IncludeXmlComments 里传的一致。常见错误是：只在 Debug 模式勾了“XML 文档文件”，Release 下没勾；或者路径拼错，比如硬写 "MyApp.xml" 却没确认实际输出名含版本号或后缀。
- 右键项目 → 属性 → 生成 → 勾选“XML 文档文件”，路径留默认（如
bin\Debug\net6.0\MyApp.xml） -
IncludeXmlComments中的xmlPath必须用Path.Combine(AppContext.BaseDirectory, xmlFile)拼，不能直接写相对路径 - 确保控制器方法上写了
/// <summary>用户登录</summary>这类三斜线注释，且includeControllerXmlComments:true已启用
AddSecurityDefinition 和 AddSecurityRequirement 必须成对出现
只加 AddSecurityDefinition("Bearer", ...) 不会出按钮；只加 AddSecurityRequirement 但没定义 scheme，会报错或按钮灰掉。二者缺一不可，且名称必须完全一致。
-
scheme参数值必须是小写"bearer"，不是"Bearer"或"JWT" -
AddSecurityRequirement里Reference.Id要和AddSecurityDefinition的第一个参数（即"Bearer"）严格匹配 - 每个需要认证的接口，控制器或方法上必须有
[Authorize]，否则 Swagger 不会自动注入该接口的安全要求
Swagger UI 点 Authorize 后请求仍无 Authorization 头？检查接口文档级标注
Swagger UI 不会全局给所有请求加 token，它只对明确声明需要认证的接口才加。即使你全局配了 scheme，如果某个 GET /api/user 方法没标 [Authorize]，它的文档就不会带安全要求，UI 就不会塞 header。
- 打开
/swagger/v1/swagger.json，搜索"security"字段，确认目标接口的路径下有类似"security": [{ "Bearer": [] }]的条目 - 若没有，说明该接口未被识别为受保护资源——检查是否漏了
[Authorize]，或是否用了自定义策略但没在AddSecurityRequirement中声明 -
BearerFormat设为"JWT"是可选提示，不影响功能，但建议加上，便于前端理解
中文界面显示异常？别动 index.html，改 JS 注入更稳妥
直接替换 index.html 容易和新版 Swagger UI 冲突；用自定义 JS 注入翻译更轻量、升级友好。关键点在于脚本加载时机和变量名。
- 在
wwwroot/swagger-custom.js中写翻译逻辑，确保它在 Swagger UI 初始化后执行（如监听window.onload或用setTimeout延迟） - 不要覆盖整个
window.SwaggerTranslator对象，而是 patch 其translate方法，避免破坏原有逻辑 - 中文化重点字段包括：
"Authorization"、"Try it out"、"Execute"、"Response Body"，注意大小写和空格
最常被忽略的是：Swagger 配置代码必须在认证中间件注册之后、UseSwaggerUI() 之前完成；而 UseAuthentication() 又必须在 UseRouting() 之后、UseEndpoints() 之前。顺序错一位，[Authorize] 就形同虚设，Swagger 按钮也只会静默失效。
