在C# Web API项目开发中，生成规范且可交互的API文档是提升团队协作效率的重要环节，Swagger结合Swashbuckle库可以快速实现这一需求，无需手动编写大量文档内容。
环境准备
本文示例基于.NET 6 Web API项目，若使用其他.NET版本，操作步骤基本一致，仅部分配置细节略有差异。
安装Swashbuckle库
首先需要通过NuGet安装Swashbuckle.AspNetCore包，有两种安装方式：
方式一：NuGet包管理器控制台
在项目目录下打开包管理器控制台，执行以下命令：
Install-Package Swashbuckle.AspNetCore
方式二：NuGet包管理器界面
右键项目选择管理NuGet程序包，搜索Swashbuckle.AspNetCore，选择最新稳定版本点击安装即可。
基础配置步骤
安装完成后需要对Swagger进行基础配置，让项目启动后能够生成并显示文档页面。
配置服务
打开Program.cs文件，添加Swagger服务注册代码：
var builder = WebApplication.CreateBuilder(args);
// 添加控制器服务
builder.Services.AddControllers();
// 注册Swagger生成器，定义一个或多个Swagger文档
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Version = "v1",
Title = "示例API文档",
Description = "这是一个使用Swashbuckle生成的C# Web API文档示例"
});
});
var app = builder.Build();
启用中间件
在同一个Program.cs文件中，添加Swagger中间件配置，让请求可以访问到文档页面：
// 配置HTTP请求管道
if (app.Environment.IsDevelopment())
{
// 启用Swagger中间件
app.UseSwagger();
// 启用Swagger UI中间件，指定Swagger JSON端点
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1版本");
// 设置Swagger UI页面路由，默认是/swagger，可自定义
options.RoutePrefix = "swagger";
});
}
app.UseAuthorization();
app.MapControllers();
app.Run();
完成以上配置后，启动项目，访问/swagger路径即可看到生成的API文档页面，页面会列出所有控制器的接口信息。
显示接口注释配置
默认情况下Swagger只会显示接口的方法名和参数类型，不会显示我们在代码里写的XML注释，需要额外配置才能展示注释内容。
开启XML注释生成
右键项目选择属性，在生成选项卡中找到输出区域，勾选XML文档文件，可以自定义文件路径，比如binDebugnet6.0MyApi.xml，保存设置。
配置Swagger读取注释
修改Program.cs中的Swagger配置，添加XML注释文件路径：
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Version = "v1",
Title = "示例API文档",
Description = "这是一个使用Swashbuckle生成的C# Web API文档示例"
});
// 获取XML注释文件路径
var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
// 包含XML注释
options.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
});
此时给控制器和接口方法添加XML注释，文档页面就会同步显示注释内容：
/// <summary>
/// 用户相关接口控制器
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
/// <summary>
/// 获取用户列表
/// </summary>
/// <param name="pageIndex">页码</param>
/// <param name="pageSize">每页条数</param>
/// <returns>用户分页列表</returns>
[HttpGet]
public IActionResult GetUsers(int pageIndex = 1, int pageSize = 10)
{
return Ok(new { pageIndex, pageSize, data = new[] { "用户1", "用户2" } });
}
}
常用配置扩展
添加接口认证配置
如果API接口需要携带Token认证，可以在Swagger中添加认证配置，方便在文档页面直接测试需要认证的接口：
builder.Services.AddSwaggerGen(options =>
{
// 之前的文档配置和XML注释配置...
// 添加Bearer Token认证配置
options.AddSecurityDefinition("Bearer", new Microsoft.OpenApi.Models.OpenApiSecurityScheme
{
Description = "JWT Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"",
Name = "Authorization",
In = Microsoft.OpenApi.Models.ParameterLocation.Header,
Type = Microsoft.OpenApi.Models.SecuritySchemeType.ApiKey,
Scheme = "Bearer"
});
options.AddSecurityRequirement(new Microsoft.OpenApi.Models.OpenApiSecurityRequirement
{
{
new Microsoft.OpenApi.Models.OpenApiSecurityScheme
{
Reference = new Microsoft.OpenApi.Models.OpenApiReference
{
Type = Microsoft.OpenApi.Models.ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
Array.Empty<string>()
}
});
});
隐藏不需要显示的接口
如果某些接口不希望出现在Swagger文档中，可以使用[ApiExplorerSettings(IgnoreApi = true)]特性标记：
/// <summary>
/// 内部测试接口，不对外暴露
/// </summary>
[ApiExplorerSettings(IgnoreApi = true)]
[HttpGet("test")]
public IActionResult TestApi()
{
return Ok("测试接口");
}
常见问题说明
- 如果启动后访问Swagger页面提示404，检查是否配置了
app.UseSwagger()和app.UseSwaggerUI()中间件，且中间件配置在app.MapControllers()之前。 - XML注释不显示时，检查XML文件路径是否正确，以及是否勾选了项目的XML文档文件生成选项。
- 不同.NET版本的服务注册方式略有差异，.NET Framework项目需要在Startup.cs的ConfigureServices方法中注册服务，在Configure方法中配置中间件。
C#SwaggerSwashbuckleAPI文档修改时间：2026-06-14 05:48:18