Swagger(Swashbuckle)：.NET项目中如何在接口端点下方添加描述文本

方法一：使用XML注释（推荐，无需额外安装包） #

• 在控制器上方添加三斜杠XML注释，示例如下：

/// <summary>
/// 这里就是你要显示在控制器名称下方的描述文本
/// </summary>
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    // 接口实现逻辑
}

• 配置项目生成XML文档文件：右键项目→属性→生成→输出，勾选「XML文档文件」，自动生成的路径无需修改
• 在Swagger配置中开启XML注释读取，.NET 6+的Program.cs配置示例如下：

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    // 读取生成的XML文档
    var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    // 第二个参数设为true才会读取控制器层面的注释
    options.IncludeXmlComments(xmlPath, true);
});

方法二：使用Swagger特性标注 #

• 安装NuGet包 Swashbuckle.AspNetCore.Annotations
• 在控制器上添加[SwaggerTag]特性直接设置描述：

[SwaggerTag(Description = "这里就是你要显示在控制器名称下方的描述文本")]
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    // 接口实现逻辑
}

• 在Swagger配置中开启注解支持：

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    options.EnableAnnotations();
});

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