本文用最通俗、最完整、最实战的方式讲透 Swagger（OpenAPI），这是 .NET Core API 开发必用工具，前后端联调全靠它！
一、Swagger 是什么？（一句话）
Swagger = 自动生成的 API 接口文档 + 在线调试工具
你写好控制器、路由、DTO 后 它自动生成网页版接口文档 可以：
- 查看所有接口
- 查看参数、返回值
- 直接在线发送请求测试
- 不用再写 Word/Markdown 文档
二、为什么必须用 Swagger？
✅ 自动生成，零维护
✅ 接口改了，文档自动更新
✅ 在线调试，不用 Postman
✅ 前后端联调神器
✅ 企业开发标配
三、一步一步集成 Swagger（.NET 6/7/8 通用）
1. 安装 NuGet 包
Swashbuckle.AspNetCore
2. 在 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 注释（显示 [Summary] 注释）
var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
options.IncludeXmlComments(xmlPath, true);
});
3. 启用中间件（必须放在 app.UseAuthorization(); 之前）
// 开发环境才启用 Swagger
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(); // UI 界面
}
4. 开启 XML 注释（让接口显示中文说明）
右键项目 → 属性 → 生成 → 勾选： ☑ 输出 XML 文档文件
这样你写的 /// 注释会自动显示在 Swagger 里！
四、启动后访问地址
https://localhost:xxxx/swagger
你会看到：
- 所有接口列表
- 可以点击 Try it out 直接测试
- 自动显示参数、返回格式、错误码
五、Swagger + 特性 = 超级接口文档
Swagger 完全依赖你之前学的 特性、路由、DTO、验证！
1. 给接口加中文说明（/// 注释）
/// <summary>
/// 根据用户ID获取用户信息
/// </summary>
/// <param name="id">用户ID</param>
/// <returns>用户信息</returns>
[HttpGet("{id}")]
public IActionResult GetUser(int id)
Swagger 会自动显示：接口名 + 说明 + 参数说明
2. DTO 里加说明
public class UserCreateDto
{
/// <summary>
/// 用户名
/// </summary>
[Required(ErrorMessage = "用户名不能为空")]
public string UserName { get; set; }
}
Swagger 会显示：字段名 + 说明 + 是否必填
3. 显示接口返回值
[HttpGet("{id}")]
[ProducesResponseType(typeof(UserDto), 200)]
[ProducesResponseType(404)]
public IActionResult Get(int id)
Swagger 自动显示：返回类型 + 状态码
六、Swagger UI 常用功能
1. 展开接口
点击接口名 → 显示详情
2. 在线调试（Try it out）
点 Try it out → 输入参数 → Execute
直接发送请求，查看返回结果
= 网页版 Postman
3. 自动生成模型（Schema）
自动显示 DTO 结构、字段、类型
七、企业级高级功能
1. 给 Swagger 加授权（Token / JWT）
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 访问需要登录的接口
2. 分组显示接口（按模块）
[ApiExplorerSettings(GroupName = "用户模块")]
public class UserController
3. 隐藏接口（不显示在文档）
[ApiExplorerSettings(IgnoreApi = true)]
public IActionResult Test()
八、Swagger 工作原理（超级简单）
- 你写：控制器 + 路由 + DTO + 特性
- Swagger 自动扫描代码
- 生成 JSON 格式接口描述
- 渲染成 网页文档 + 调试界面
九、Swagger 核心总结（背会）
- Swagger = 自动API文档 + 在线调试
- 依赖：路由 + 特性 + DTO + 数据验证
- 自动生成，不用手写文档
- 支持：注释、参数、返回值、状态码、授权
- 企业开发 100% 必用
