老实说，

最通俗、最完整、最实战的方式讲透 Swagger这是 .NET Core API 开发必用工具前后端联调全靠它！

从你可能会遇到来看。

• 接口文档手写费时费力，一旦接口变更需要重新整理。
• 前后端沟通效率低下缺少统一可视化参考。话说回来，
• 测试接口繁琐。需要频繁切换 Postman 或手工编写请求。
-
• `<sup>-`></sup>

Swagger = 自动生成的 API 接口文档 + 在线调试工具

你写好控制器、路由、DTO 后它自动生成网页版接口文档可以：

• 查看所有接口
• 查看参数、返回值
• 直接在线发送请求测试

二、为什么必须用 Swagger？

✅ 自动生成，零维护 ✅ 接口改了文档自动更新 ✅ 在线调试。不用 Postman ✅ 前后端联调工具 ✅ 公司开发标配

三、一步一步集成 Swagger

. 安装 NuGet 包

Swashbuckle.AspNetCore

. 在 Program.cs 中注册服务

// 注册 Swagger 生成器
builder.Services.AddSwaggerGen;// 如果你想显示注释
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1"。new Microsoft.OpenApi.Models.OpenApiInfo
{
Title = "我的项目 API",Version = "v1",Description = ".NET Core 项目接口文档"
});
// 包含 XML 注释
var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly.GetName.Name}.xml";var xmlPath = Path.Combine;options.IncludeXmlComments;})，

. 启用中间件

// 开发环境才启用 Swagger
if )
{
app.UseSwagger;app.UseSwaggerUI;// UI 界面
}

. 开启 XML 注释

右键项目 → 属性 → 生成 → 勾选：☑ 输出 XML 文档文件

这样你写的 /// 注释会自动显示在 Swagger 里！这代表着每次改动代码都能即时同步到文档，无需手动维护。

四、启动后访问地址

https://localhost:xxxx/swagger

你会看到的观点是，

• 所有接口列表
• 可以点击 Try it out 直接测试
• 自动显示参数、返回格式、错误码
-->

五、Swagger + 特性 = 超级接口文档

Swagger 完全依赖你之前学的 特性、路由、DTO、验证

. 给接口加中文说明

/// 

/// 根据使用者ID获取使用者信息
/// 
/// 使用者信息
public IActionResult GetUser
{
}

swagger 会自动显示： “ 接口名 + 说明 + 参数说明 ”

---

. DTO 里加说明

csharp public class UserCreateDto{ ///

/// 使用者名 ///

public string UserName { get;set，} }

swagger 会显示： “ 字段名 + 说明 + 是否必填 ”

---

. 显示接口返回值

csharp public IActionResult Get { }

swagger 自动显示： “ 返回类型 + 状态码 ”

---

六 、swagger UI 常用功能

. 展开 接口

点击 接口名 → 显示详情

. 在线 调试

点 Try it out → 输入参数 → Execute 直接发送请求。查看返回结果 = 网页版 Postman

. 自动生成模型

自动显示 DTO 结构 、字段 、类型

七 、公司级高级功能

. 给 swagger 加授权

csharp builder.Services.AddSwaggerGen(c =>{ c.AddSecurityDefinition("Bearer",new OpenApiSecurityScheme { In = ParameterLocation.Header,Type= SecuritySchemeType.Http,BearerFormat="JWT",Scheme="bearer"} );c.AddSecurityRequirement(new OpenApiSecurityRequirement { {new OpenApiSecurityScheme{Reference=new OpenApiReference{ Type=ReferenceType.SecurityScheme。Id="Bearer"} },new string{} }});})，

说到效果，swagger 可以输入 Token 访问需要登录的接口

---

. 分组 显示 接口

csharp public class UserController : ControllerBase {}

---

. 隐藏 接口

csharp public IActionResult Test {}

---

八 、swagger 工作原理

1️⃣ 写好 控制器+路由+DTO+特性 🔍 swagger 自动扫描代码 🗂️ 生成 JSON 格式接口描述 🌐 渲染成 网页 文档+ 调试界面

---

九 、swagger 主要

2️⃣ ✅依赖： 路由 | 特性 | DTO | 数据验证

3️⃣ ⚡️自动生成。无需手工撰写

4️⃣ 🚀支持： 注释 | 参数 | 返回值 | 状态码 | 授权

5️⃣ 🌟 公司开发 % 必用

。

---