Swashbuckle.AspNetCore 安装失败需检查 .NET 版本兼容性：.NET 5 用 5.6.3，.NET 6+ 用 6.5.0+，.NET 8 推荐 7.0.0+；务必配对注册 AddSwaggerGen、UseSwagger 和 UseSwaggerUI，并启用 XML 注释与正确静态资源路径。
Swashbuckle.AspNetCore 装不进去？检查 .NET 版本和包兼容性
Swagger 在 C# 里靠 Swashbuckle.AspNetCore 实现，不是原生功能。.NET 6+ 项目默认能装最新版，但如果你用的是 .NET 5 或更早版本，Swashbuckle.AspNetCore 6.x 就不支持——会报错 NU1202: Package Swashbuckle.AspNetCore 6.5.0 is not compatible with net5.0。
实操建议：
- 查清项目目标框架：
dotnet --list-sdks和 csproj 里的<targetframework></targetframework> - .NET 5 用
Swashbuckle.AspNetCore5.6.3；.NET 6+ 推荐 6.5.0+；.NET 8 用 7.0.0+ 更稳 - 别直接 NuGet 搜“Swagger”，搜全名
Swashbuckle.AspNetCore，避免装错第三方包（比如过时的Swashbuckle）
ConfigureServices 里 AddSwaggerGen 不生效？顺序和中间件注册要配对
只在 Program.cs 里调 services.AddSwaggerGen() 是不够的，还必须在 app.UseSwagger() 和 app.UseSwaggerUI() 才能访问 /swagger 页面。漏掉任一环，浏览器打开就是 404 或空白页。
常见错误现象：
- 访问
/swagger返回 404 → 没调app.UseSwagger()或路径被其他中间件拦截 - 页面加载但没接口列表 →
AddSwaggerGen()里没配置c.SwaggerDoc()，或控制器没加[ApiController]/ HTTP 方法特性 - 文档里参数全是
object→ 忘了启用 XML 注释或没指定注释文件路径
实操建议（.NET 6+ Program.cs）：
builder.Services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" }); });app.UseSwagger(); app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1"));- XML 注释开启：csproj 加
<generatedocumentationfile>true</generatedocumentationfile>，AddSwaggerGen里补上c.IncludeXmlComments(filePath)
Controller 参数显示为 object？模型绑定和 XML 注释没对齐
Swagger 默认靠反射读取 Action 签名，但复杂对象（如自定义 DTO）若没公开属性、没 XML 注释、或用了 [FromBody] 却没设 Content-Type: application/json，就会退化成 object 显示，根本看不出字段结构。
使用场景：POST 接口接收 ProductDto，文档里却只写 “productDto (object)”
实操建议：
- DTO 属性必须是
public，且有 getter/setter（init也行，但 .NET 6+ 才完整支持） - XML 注释要写在类和属性上，例如
/// <summary>商品名称</summary>，否则字段描述为空 - 别依赖
[FromQuery]自动推导：显式用c.SchemaFilter<customschemafilter>()</customschemafilter>控制生成逻辑，比猜强 - 如果 DTO 继承自基类，确保基类属性也被 XML 注释覆盖，否则子类文档缺字段
部署后 Swagger UI 打不开？静态资源路径和反向代理要调准
本地跑得好，上线 Nginx/Apache/IIS 后 /swagger 白屏或 JS 报 404，大概率是 Swagger 的静态资源（JS/CSS）没映射对。Swagger UI 默认从 /swagger/ui/ 或 /swagger/v1/swagger.json 加载，但反向代理常把前缀截断。
性能与兼容性影响：
- IIS 下未启用
StaticFileMiddleware→ CSS/JS 404，UI 崩溃 - Nginx 配置
location /swagger { proxy_pass http://backend; }缺少结尾/→ 请求变成/swagger/swagger-ui-bundle.js而非/swagger/ui/swagger-ui-bundle.js - 生产环境默认禁用 Swagger（
if (app.Environment.IsDevelopment())），上线忘了放开或改条件
实操建议：
- 生产启用时，别删
IsDevelopment判断，改成app.Environment.IsEnvironment("Staging")并配好环境变量 - Nginx 示例修正：
location /swagger/ { proxy_pass http://backend/swagger/; }（注意双/） - 确认
app.UseStaticFiles()在UseSwaggerUI()之前调用，否则 UI 资源无法服务
Swagger 文档不是“装完就跑”，它卡点都在细节：XML 文件路径拼错、中间件顺序颠倒、反向代理多转一次路径、甚至 DTO 属性少了个 public —— 这些地方不动代码，光看文档根本发现不了。
