swagger在c#中需通过swashbuckle.aspnetcore实现三步闭环：生成json（swaggergen）、托管json（useswagger）、渲染ui（useswaggerui）；缺一不可，且依赖.net版本与包版本严格匹配，中间件注册顺序及xml文档配置也必须正确。
Swagger 文档在 C# 里不是开箱即用的功能，它依赖 Swashbuckle.AspNetCore 包完成三件事：生成 JSON 描述（SwaggerGen）、托管该 JSON（UseSwagger）、渲染成网页（UseSwaggerUI）。漏掉任意一环，页面打不开、接口不显示、参数变 object——都不是配置“没生效”，而是根本没连通。
安装 Swashbuckle.AspNetCore 时版本对不上就直接失败
包装不进去？十有八九是 .NET 版本和包版本不匹配。NuGet 搜 “Swagger” 容易装错旧包（比如 Swashbuckle），必须搜全名 Swashbuckle.AspNetCore。
- .NET 5 项目只能用
Swashbuckle.AspNetCore 5.6.3；装 6.x 会报NU1202: Package is not compatible with net5.0 - .NET 6/7 项目推荐
6.5.0+；.NET 8 项目建议用7.0.0+（截至 2026 年 4 月，7.0.0 是最稳的 LTS 兼容版） - 检查目标框架：
dotnet --list-sdks和.csproj中的<targetframework></targetframework>必须一致
Program.cs 里三处注册缺一不可且顺序敏感
AddSwaggerGen() 只负责“生成文档结构”，不调 UseSwagger() 就没有 /swagger/v1/swagger.json 端点；不调 UseSwaggerUI() 就没有网页界面。中间件顺序错了也会白配。
-
builder.Services.AddSwaggerGen()放在AddControllers()之后、AddEndpointsApiExplorer()之前（.NET 6+ 必须显式加这句） -
app.UseSwagger()必须在app.UseRouting()之后、app.UseEndpoints()或app.MapControllers()之前 -
app.UseSwaggerUI(c => c.SwaggerEndpoint(...))要紧挨着UseSwagger()，别被UseAuthentication()之类中间件隔开
Controller 参数显示为 object？多半是 XML 注释没对齐
Swagger 默认靠反射读取 DTO 属性，但若属性非 public、没 getter/setter（或只用 init 但项目是 .NET 5）、XML 注释路径没配对，就会退化成 object，字段结构完全丢失。
-
.csproj里加：<generatedocumentationfile>true</generatedocumentationfile> -
AddSwaggerGen()里补上：c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml")) - DTO 所有要暴露的字段必须是
public，且至少有一个可访问的 setter（init在 .NET 6+ 可用，.NET 5 不行） - 控制器方法上加
[HttpGet]等 HTTP 特性，类上加[ApiController]，否则SwaggerGen扫描不到
Swagger UI 页面空白或 404 的真实原因
不是“Swagger 没启动”，而是请求路径被拦截或文档未生成。浏览器打开 /swagger 返回 404，说明 UseSwagger() 没注册或被前置中间件吞了；页面加载但没接口，大概率是 SwaggerDoc("v1", ...) 没调，或控制器路由没启用（MapControllers() 缺失）。
- 先手动访问
/swagger/v1/swagger.json：能打开 JSON 就说明生成成功，问题出在 UI 渲染；打不开就是UseSwagger()没生效 - 检查控制器是否启用路由：
app.MapControllers()或app.UseEndpoints(e => e.MapControllers())必须存在 - 开发环境外发布时，XML 文件不会自动拷到输出目录，得手动加
<copytooutputdirectory>PreserveNewest</copytooutputdirectory>到.csproj里
最常被忽略的一点：Swagger 文档不是静态快照，它每次请求都动态反射当前程序集。所以改了 DTO 属性但没重启应用，文档还是旧的；加了新接口但没加 HTTP 特性，它就永远“看不见”。别查缓存，查代码本身是否满足反射前提。
