.NET Core Swagger 超详细讲解（从入门到企业级）

本文用最通俗、最完整、最实战 的方式讲透 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 中注册服务

csharp 复制代码

// 注册 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(); 之前）

csharp 复制代码

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

4. 开启 XML 注释（让接口显示中文说明）

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

这样你写的 /// 注释会自动显示在 Swagger 里！

四、启动后访问地址

bash 复制代码

https://localhost:xxxx/swagger

你会看到：

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

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

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

1. 给接口加中文说明（/// 注释）

csharp 复制代码

/// <summary>
/// 根据用户ID获取用户信息
/// </summary>
/// <param name="id">用户ID</param>
/// <returns>用户信息</returns>
[HttpGet("{id}")]
public IActionResult GetUser(int id)

Swagger 会自动显示：接口名 + 说明 + 参数说明

2. DTO 里加说明

csharp 复制代码

public class UserCreateDto
{
    /// <summary>
    /// 用户名
    /// </summary>
    [Required(ErrorMessage = "用户名不能为空")]
    public string UserName { get; set; }
}

Swagger 会显示：字段名 + 说明 + 是否必填

3. 显示接口返回值

csharp 复制代码

[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）

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 访问需要登录的接口

2. 分组显示接口（按模块）

csharp 复制代码

[ApiExplorerSettings(GroupName = "用户模块")]
public class UserController

3. 隐藏接口（不显示在文档）

csharp 复制代码

[ApiExplorerSettings(IgnoreApi = true)]
public IActionResult Test()

八、Swagger 工作原理（超级简单）

你写：控制器 + 路由 + DTO + 特性
Swagger 自动扫描代码
生成 JSON 格式接口描述
渲染成 网页文档 + 调试界面

九、Swagger 核心总结（背会）

Swagger = 自动API文档 + 在线调试
依赖：路由 + 特性 + DTO + 数据验证
自动生成，不用手写文档
支持：注释、参数、返回值、状态码、授权
企业开发 100% 必用