Swagger在C#中需通过Swashbuckle.AspNetCore完整配置：AddSwaggerGen生成JSON、UseSwagger暴露JSON、UseSwaggerUI渲染页面，三者缺一不可且顺序严格；版本须匹配.NET框架（如.NET 8用7.0.0+），并正确启用XML注释与特性解析。
Swagger 在 C# 里不是装个包就自动出文档的功能，它必须靠 Swashbuckle.AspNetCore 包完成三件事：生成 JSON（AddSwaggerGen）、暴露该 JSON（UseSwagger）、渲染成网页（UseSwaggerUI）。漏掉任意一环，/swagger 页面就是 404、空白，或参数全显示为 object。
Swashbuckle.AspNetCore 版本和 .NET 框架不匹配直接报错
装不上或运行时报 NU1202: Package is not compatible with netX.0，基本就是版本对不上。NuGet 搜 “Swagger” 容易误装旧包 Swashbuckle，必须搜全名 Swashbuckle.AspNetCore。
- .NET 5 项目只能用
Swashbuckle.AspNetCore 5.6.3 - .NET 6/7 项目推荐
6.5.0或更高（如6.6.2） - .NET 8 项目建议用
7.0.0及以上（截至 2026 年 4 月，7.0.0是最稳的 LTS 兼容版） - 检查目标框架：
dotnet --list-sdks和.csproj中的<TargetFramework>必须一致
AddSwaggerGen + UseSwagger + UseSwaggerUI 缺一不可且顺序敏感
只调 AddSwaggerGen() 不会生成可访问的 JSON；只调 UseSwagger() 不会加载 UI；中间件顺序错了，Swagger 就被路由或认证中间件拦住。
-
builder.Services.AddEndpointsApiExplorer()必须在AddSwaggerGen()之前（.NET 6+ 显式要求） -
app.UseSwagger()必须在app.UseRouting()之后、app.UseEndpoints()或app.MapControllers()之前 -
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1"))要紧挨着UseSwagger()，别被UseAuthentication()等隔开 -
AddSwaggerGen()里至少得写c.SwaggerDoc("v1", new OpenApiInfo { Title = "...", Version = "v1" })，否则没文档根节点
Controller 参数显示为 object？XML 注释根本没加载成功
写了 /// <summary>xxx</summary> 却没出现在 Swagger UI 里，90% 是 XML 文件压根没生成，或生成了但路径不对、没注册进 AddSwaggerGen。
-
.csproj中加：<GenerateDocumentationFile>true</GenerateDocumentationFile> -
AddSwaggerGen()里必须显式调c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "YourApp.xml"))，文件名默认是程序集名+.xml，大小写敏感 - 发布后检查输出目录（如
publish/YourApp.xml）是否真有该文件，Debug 目录下有 ≠ 发布后也有 - DTO 所有字段必须是
public，且带 getter（init在 .NET 6+ 可用，.NET 5 不行）；private 字段、只读属性、无 setter 的init（低版本）都会退化为object
ProducesResponseType 不显示模型？响应类型推导没打开
加了 [ProducesResponseType(typeof(User), StatusCodes.Status200OK)]，但 Swagger UI 里 Response Body 还是空或显示 object，问题常出在 Swagger 没启用特性解析。
-
AddSwaggerGen()配置里要加c.EnableAnnotations()（启用ProducesResponseType和SwaggerResponseAttribute） - 返回类型别用模糊写法，比如
IEnumerable<User>或Task<IResult>，Swagger 推断容易失败；显式写成[ProducesResponseType(typeof(IEnumerable<User>), 200)] - 如果用了泛型或继承结构，考虑补上
c.UseOneOfForPolymorphism() - 控制器类必须标
[ApiController]，方法必须有 HTTP 特性（如[HttpGet]），否则AddSwaggerGen根本扫描不到这个接口
最常被忽略的点：XML 注释路径是运行时路径，不是编译时路径；AppContext.BaseDirectory 在 IIS、Docker、Azure App Service 下可能和你本地调试时不一样，硬编码路径极易失效。建议用 Assembly.GetExecutingAssembly().GetName().Name + ".xml" 拼接，并加日志验证文件是否存在。
