如何为WebAPI的DTO属性添加Swagger文档说明

步骤1：给DTO属性添加XML注释 #

直接在GetPackByIdFilteredDto的每个属性上方添加<summary>注释，示例如下：

public class GetPackByIdFilteredDto
{
    /// <summary>
    /// 日期类型标识（替换为实际业务描述）
    /// </summary>
    public string Dt { get; set; }

    /// <summary>
    /// 数据分类代码（替换为实际业务描述）
    /// </summary>
    public string Dc { get; set; }

    /// <summary>
    /// 数据源标识（替换为实际业务描述）
    /// </summary>
    public string Ms { get; set; }
}

步骤2：启用项目XML文档生成 #

右键WebAPI项目 → 选择「属性」→ 切换到「生成」标签页 → 勾选「XML文档文件」，可保留默认输出路径或自定义到项目目录。

步骤3：配置Swagger读取XML注释文件 #

在项目的Program.cs（.NET 6+）或Startup.cs（.NET 5及更早版本）中，修改Swagger配置逻辑，添加读取XML注释的代码：

// .NET 6+ Program.cs示例
builder.Services.AddSwaggerGen(c =>
{
    // 获取当前程序集的XML文档路径
    var xmlFileName = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    
    // 加载XML注释，includeControllerXmlComments设为true会同时读取控制器的注释
    c.IncludeXmlComments(xmlFilePath, includeControllerXmlComments: true);
});

若DTO类放在单独的类库项目中，需额外添加类库生成的XML文件路径：

var dtoXmlFilePath = Path.Combine(AppContext.BaseDirectory, "你的DTO类库名称.xml");
c.IncludeXmlComments(dtoXmlFilePath);

补充：完善filterDto的参数注释 #

可以给控制器方法中的filterDto参数补全注释，让Swagger中该参数的整体描述更清晰：

/// <param name="filterDto">产品包筛选条件，包含日期类型、数据分类等参数</param>

内容的提问来源于stack exchange，提问作者DIamondGeezer