在C# Web API项目开发过程中，我们通常会为控制器、接口方法、参数等添加XML文档注释，这些注释可以清晰说明接口的功能、参数的含义和返回值的说明。而Swagger作为主流的API文档生成工具，默认不会自动读取这些XML注释，需要经过特定的配置才能实现注释的同步展示。
第一步：开启C#项目的XML文档注释生成
首先需要让项目在编译时生成包含注释的XML文件，操作步骤如下：
- 右键点击项目，选择属性
- 在左侧菜单选择生成，找到输出区域
- 勾选XML文档文件选项，默认会自动填充XML文件的生成路径，也可以自定义路径，比如
binDebugnet8.0MyApi.xml - 保存项目属性配置，重新编译项目后，就会在指定路径生成XML文件
需要注意，如果项目中存在没有写注释的公共类型或成员，编译时会出现警告，可以在生成页面取消勾选警告视为错误的相关选项，或者在需要忽略的位置添加#pragma warning disable 1591和#pragma warning restore 1591来屏蔽特定代码的警告。
第二步：安装Swagger相关NuGet包
如果是.NET Core或.NET 5及以上版本的项目，需要安装Swagger的NuGet包，常用的包是Swashbuckle.AspNetCore，可以通过NuGet包管理器搜索安装，也可以使用命令行安装：
dotnet add package Swashbuckle.AspNetCore
第三步：配置Swagger读取XML文件
安装完包之后，需要在项目的Program.cs文件中添加Swagger的配置，核心是指定XML文件的路径，让Swagger加载其中的注释内容。
基础配置示例
以下是.NET 8项目的完整配置示例：
using Microsoft.OpenApi.Models;
var builder = WebApplication.CreateBuilder(args);
// 添加控制器服务
builder.Services.AddControllers();
// 配置Swagger服务
builder.Services.AddSwaggerGen(options =>
{
// 设置Swagger文档的基本信息
options.SwaggerDoc("v1", new OpenApiInfo
{
Title = "我的API文档",
Version = "v1",
Description = "这是基于C# XML注释生成的API文档"
});
// 获取XML文件的路径
var xmlFilename = "MyApi.xml"; // 这里替换为你的XML文件名
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFilename);
// 包含XML注释文件
options.IncludeXmlComments(xmlPath);
// 如果需要同时包含控制器所在的XML和模型所在的XML，可以添加多个IncludeXmlComments
// var modelXmlPath = Path.Combine(AppContext.BaseDirectory, "MyApi.Models.xml");
// options.IncludeXmlComments(modelXmlPath);
});
var app = builder.Build();
// 开发环境启用Swagger中间件
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
});
}
app.UseAuthorization();
app.MapControllers();
app.Run();
配置说明
IncludeXmlComments方法用于指定要加载的XML文件路径，如果项目中有多个XML文件（比如控制器和模型分属不同项目），可以多次调用该方法添加多个XML文件AppContext.BaseDirectory会获取应用程序的运行目录，XML文件生成在输出目录，所以可以直接拼接路径找到文件- 如果XML文件不存在，Swagger启动时会抛出异常，需要确保编译后XML文件已经生成在对应路径
第四步：编写XML注释并验证效果
配置完成后，我们可以为接口添加XML注释，然后启动项目查看Swagger文档的效果。
XML注释示例
using Microsoft.AspNetCore.Mvc;
/// <summary>
/// 用户管理相关接口
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
/// <summary>
/// 获取用户列表
/// </summary>
/// <param name="pageIndex">页码，从1开始</param>
/// <param name="pageSize">每页数量，最大100</param>
/// <returns>返回分页后的用户列表</returns>
[HttpGet]
public IActionResult GetUsers(int pageIndex = 1, int pageSize = 10)
{
// 模拟返回数据
return Ok(new { pageIndex, pageSize, data = new[] { "用户1", "用户2" } });
}
/// <summary>
/// 根据ID获取用户详情
/// </summary>
/// <param name="id">用户唯一标识</param>
/// <returns>返回用户详情信息</returns>
[HttpGet("{id}")]
public IActionResult GetUserById(int id)
{
return Ok(new { id, name = "测试用户", age = 20 });
}
}
启动项目后，访问Swagger UI页面，就可以看到接口上方显示了我们在XML注释中写的summary内容，参数的说明也会展示在参数列表的下方，返回值的说明会展示在接口响应区域。
常见问题及解决方法
- XML文件找不到：检查XML文件名是否和配置中的一致，编译后是否生成了XML文件，路径拼接是否正确，可以在代码中添加
if (!File.Exists(xmlPath)) throw new FileNotFoundException("XML文件不存在", xmlPath);来排查路径问题 - 注释不显示：检查XML文件内容是否包含对应的注释，确认
IncludeXmlComments方法已经正确调用，并且XML文件的生成路径和配置的路径一致 - 模型注释不显示：如果模型的XML注释在另一个项目的XML文件中，需要把这个XML文件也复制到当前项目的输出目录，并且添加对应的
IncludeXmlComments配置
注意：发布项目时，需要确保XML文件会一起发布到输出目录，否则生产环境Swagger会无法读取注释。可以在项目文件中添加<None Update="MyApi.xml" CopyToOutputDirectory="PreserveNewest" />来指定XML文件复制到输出目录。
C#XML文档注释SwaggerAPI文档生成Swagger_UI修改时间：2026-07-12 18:27:28