swagger非开箱即用，须手动安装swashbuckle.aspnetcore（版本需匹配.net框架）、配置addswaggergen/useswagger/useswaggerui三处中间件，并启用xml注释生成与正确路径加载，缺一不可。
Swagger 不是开箱即用的功能，必须手动装包、配中间件、启 XML 注释，漏掉任一环，/swagger 页面就打不开或接口列表为空。
Swashbuckle.AspNetCore 版本和 .NET 框架必须严格匹配
直接 Install-Package Swashbuckle.AspNetCore 容易装错——它默认拉最新版，但新版不兼容旧框架。实际运行时会报 NU1202: Package Swashbuckle.AspNetCore 6.5.0 is not compatible with net5.0 这类错误。
- .NET 5 项目只能用
Swashbuckle.AspNetCore 5.6.3 - .NET 6/7 项目推荐
6.5.0或更高（如6.6.2） - .NET 8 项目建议用
7.0.0及以上，7.5.0已稳定支持 OpenAPI 3.1 - 检查目标框架：看
.csproj里的<targetframework>net6.0</targetframework>，再查dotnet --list-sdks
Program.cs 里三处调用缺一不可
只加 AddSwaggerGen() 是没用的。Swagger 文档生成、HTTP 路由暴露、UI 渲染是三个独立环节，顺序和位置都敏感。
-
builder.Services.AddSwaggerGen()：注册文档生成器，必须配置c.SwaggerDoc("v1", ...) -
app.UseSwagger()：启用中间件，把/swagger/v1/swagger.json暴露为可访问路径；必须放在app.UseRouting()之后、app.UseEndpoints()之前 -
app.UseSwaggerUI(c => c.SwaggerEndpoint(...))：加载 UI，路径要和上面SwaggerDoc的版本名一致（比如都用v1） - 控制器没加
[ApiController]或方法没标[HttpGet]等特性，SwaggerGen 就扫描不到接口，文档空白
XML 注释不生效？路径、生成、加载全得对上
注释显示不出来，90% 是 XML 文件根本没生成，或生成了但 Swagger 找不到。不是“写了注释就自动显示”。
- 在项目属性 → 生成 → 勾选
XML 文档文件，路径建议用默认值（如bin\MyApi.xml），避免手写路径出错 -
.csproj中确认有<generatedocumentationfile>true</generatedocumentationfile> -
AddSwaggerGen()里必须显式调c.IncludeXmlComments(filePath)，filePath要是运行时能访问到的绝对路径，例如：Path.Combine(AppContext.BaseDirectory, "MyApi.xml") - DTO 类属性要是
public，且带 getter/setter（init在 .NET 6+ 可用，但低版本会显示为object）
中文界面和控制器描述不是默认功能
Swagger UI 默认全是英文，Controller 类上的 XML 注释也不会自动变成分组标题——这些都要自己补逻辑。
- 中文翻译靠 JS 注入：在
UseSwaggerUI()里加c.InjectJavaScript(assembly, "YourApp.Scripts.swagger-zh.js")，JS 文件里用字典替换界面文本（注意保留GET/POST等术语原样） - 控制器描述需额外处理：默认
IncludeXmlComments()只读方法级注释；要显示 Controller 标题，得写个自定义IDocumentFilter或ISwaggerProvider实现，从 XML 中提取<summary></summary>并注入到Tags或Description - 发布时 XML 文件不会自动拷到输出目录，得手动加
<copytooutputdirectory>PreserveNewest</copytooutputdirectory>到.csproj里
最常被忽略的是 XML 文件的运行时路径和发布行为——本地调试能显示，一发布就变空，基本就是 bin 下没 XML 或路径拼错了。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
