在C# WebAPI项目开发过程中，接口文档是前后端协作的重要依据，手动维护接口文档不仅效率低，还容易出现文档与实际接口不匹配的问题，而Swagger可以自动根据项目中的接口代码生成可视化的接口文档，大幅降低文档维护成本。
环境准备
本文示例基于.NET 6的WebAPI项目，首先需要确保项目已经创建完成，并且可以正常启动运行。如果使用的是更早的.NET Framework版本的WebAPI项目，配置逻辑类似，只是引入包的方式和中间件注册的位置会有细微差异。
安装Swagger相关NuGet包
打开项目的NuGet包管理器，搜索并安装Swashbuckle.AspNetCore包，这是Swagger在.NET生态中的核心实现包，安装完成后就可以开始配置Swagger的相关功能。
基础配置步骤
注册Swagger服务
打开项目中的Program.cs文件，在构建应用的主逻辑中添加Swagger服务的注册代码，具体代码如下：
// 注册Swagger生成器服务，配置文档基础信息
builder.Services.AddSwaggerGen(options =>
{
// 设置文档的标题
options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Title = "示例WebAPI接口文档",
Version = "v1",
Description = "这是基于C# WebAPI生成的Swagger接口文档示例"
});
});
启用Swagger中间件
服务注册完成后，需要在请求管道中启用Swagger的中间件，让Swagger可以在项目运行时生成并展示接口文档，代码如下：
var app = builder.Build();
// 判断当前环境是否为开发环境，开发环境下启用Swagger
if (app.Environment.IsDevelopment())
{
// 启用Swagger中间件，生成接口文档的JSON数据
app.UseSwagger();
// 启用Swagger UI中间件，展示可视化的接口文档页面
app.UseSwaggerUI(options =>
{
// 设置Swagger UI页面的文档端点
options.SwaggerEndpoint("/swagger/v1/swagger.json", "示例WebAPI接口文档 v1");
// 设置Swagger UI的路由前缀，默认是/swagger
options.RoutePrefix = "swagger";
});
}
验证配置效果
完成上述配置后，启动项目，在浏览器中访问https://localhost:端口号/swagger，就可以看到自动生成的接口文档页面，页面中会展示项目中所有的接口路由、请求方式、参数说明等信息。
接口注释显示配置
默认情况下Swagger不会显示接口和参数的注释内容，需要额外配置才能将代码中的XML注释同步到接口文档中。首先需要在项目属性中开启XML文档生成，步骤如下：
- 右键点击项目，选择属性
- 在生成选项卡中找到输出部分，勾选生成XML文档文件
- 记录下XML文件的路径，后续配置会用到
然后在AddSwaggerGen的配置中添加读取XML文档的代码：
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Title = "示例WebAPI接口文档",
Version = "v1",
Description = "这是基于C# WebAPI生成的Swagger接口文档示例"
});
// 获取XML文档的路径
var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
// 包含XML文档中的注释
options.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
});
配置完成后，在控制器的接口方法上添加XML注释，重新启动项目就可以在Swagger文档中看到对应的注释内容了。
常见问题说明
- 如果访问Swagger页面出现404错误，需要检查中间件的启用顺序，确保
UseSwagger和UseSwaggerUI在路由中间件之前注册 - 如果XML注释没有显示，需要检查XML文件的路径是否正确，以及是否勾选了生成XML文档文件的选项
- 生产环境建议关闭Swagger文档的访问权限，避免接口信息泄露，可以通过环境变量判断只在开发环境启用相关中间件