Swagger在ASP.NET Core中需安装Swashbuckle.AspNetCore NuGet包，配置AddSwaggerGen、UseSwagger、UseSwaggerUI中间件，启用XML注释与ProducesResponseType解析，并适配部署路径。
Swagger在ASP.NET Core里不是插件，是NuGet包+中间件组合
Swagger文档生成在ASP.NET Core中靠的是 Swashbuckle.AspNetCore 这个官方推荐的NuGet包，不是内置功能，也不是“装个插件就完事”。它由三部分组成：API描述（SwaggerGen）、UI渲染（SwaggerUI）和中间件管道集成。漏掉任一环，页面打不开或文档为空。
- 必须安装
Swashbuckle.AspNetCore（6.4+ 支持 .NET 6/7/8，别用老版本Swashbuckle） -
Program.cs里要调用AddSwaggerGen()和UseSwagger()+UseSwaggerUI()，顺序不能反——UseSwagger()必须在UseRouting()之后、UseEndpoints()之前 - 控制器方法没加 HTTP 方法特性（如
[HttpGet]）或没启用控制器路由（MapControllers()），SwaggerGen就扫描不到接口，文档空白
Controller参数不显示？多半是没开XML注释或没配 IncludeXmlComments
Swagger默认不读取C# XML注释，所以即使你写了 /// <summary></summary>，文档里照样没说明。想让参数、返回值、方法描述出现，得手动打开开关，并确保编译时生成XML文件。
- 项目文件（
.csproj）里加：<generatedocumentationfile>true</generatedocumentationfile> -
Program.cs中配置AddSwaggerGen时，显式调用c.IncludeXmlComments()，路径要用AppContext.BaseDirectory拼接，例如：c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "YourApp.xml")) - XML文件名默认是程序集名+.xml，大小写敏感；如果发布后找不到文件，检查发布输出目录是否真有该文件，而不是只在Debug目录下存在
ProducesResponseType 不生效？因为没配 SwaggerGen 的响应类型推导
标注了 [ProducesResponseType(typeof(User), StatusCodes.Status200OK)] 却在Swagger UI里看不到响应模型？问题常出在两个地方：一是没启用响应类型自动发现，二是泛型或复杂类型没正确注册。
-
AddSwaggerGen配置里默认不展开ProducesResponseType特性，需加c.UseOneOfForPolymorphism()或更关键的：c.EnableAnnotations()（启用SwaggerResponseAttribute和ProducesResponseType解析） - 若返回类型是
IEnumerable<user></user>或Task<iresult></iresult>，Swagger可能无法自动推断——建议显式写成[ProducesResponseType(typeof(IEnumerable<user>), 200)]</user>，并确保User类有 public getter 属性（private set 可以，但字段不行） - 使用
Microsoft.AspNetCore.Mvc.ApiExplorer的 API 发现机制依赖ApiConventionType，如果用了自定义约定或跳过AddControllersWithViews()而直接用AddMvcCore()，得手动补AddApiExplorer()
部署到IIS或Nginx后Swagger UI打不开？路径前缀没对齐
本地 https://localhost:5001/swagger 好好的，部署后变成 https://example.com/myapp/swagger 就报404或白屏——根本原因是 Swagger UI 的请求路径（如 /swagger/v1/swagger.json）被反向代理截断或重写，而前端JS仍按根路径发请求。
- 在
UseSwaggerUI配置里必须设c.SwaggerEndpoint("/myapp/swagger/v1/swagger.json", "My API V1")，路径要和实际部署URL前缀一致 - 同时配
c.RoutePrefix = "myapp/swagger"（注意：不是完整URL，是相对路径），否则UI资源（CSS/JS）加载失败 - IIS下若用了
web.config的httpRedirect或 URL重写规则，会干扰/swagger/*请求，建议对swagger路径加<rule name="Swagger" stopprocessing="true"></rule>排除
Swagger最麻烦的从来不是“怎么加”，而是“加完为什么没效果”——每个环节都依赖上一个环节的输出，XML文件路径错、中间件顺序错、反向代理没透传、甚至控制器没继承 ControllerBase，都会导致某个小环节静默失败。盯住浏览器F12里Network标签页，看第一个 swagger.json 请求返回啥，比翻十遍文档都管用。
