如何使用Swashbuckle为REST资源添加控制器级文档描述？

你在Swagger Editor里写的name: Customers和对应的description属于OpenAPI规范里的Tags配置，对应Swagger UI里的分组标签说明。要让Swashbuckle把这些描述输出到最终的Swagger文档里，按以下步骤操作即可：

1. 给控制器绑定对应的Tag #

在控制器类上方添加[ApiExplorerSettings]特性，指定GroupName为你要关联的Tag名称：

[ApiController]
[Route("api/customers")]
[ApiExplorerSettings(GroupName = "Customers")]
public class CustomersController : ControllerBase
{
    // 控制器业务逻辑
}

同理，Devices控制器也需要添加[ApiExplorerSettings(GroupName = "Devices")]特性。

2. 配置Swashbuckle添加Tag描述 #

有两种方式可以给Tag添加描述：

方式一：手动在Swagger配置里指定 #

在Program.cs（或Startup.cs）的AddSwaggerGen方法中，通过Tags方法直接定义每个Tag的名称和描述：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API标题", Version = "v1" });
    
    // 手动添加Tag描述
    c.Tags.Add(new OpenApiTag
    {
        Name = "Customers",
        Description = "Access to customer information"
    });
    c.Tags.Add(new OpenApiTag
    {
        Name = "Devices",
        Description = "Access to device information"
    });
});

方式二：通过XML注释自动导入 #

如果想通过代码注释维护Tag描述，可按以下步骤配置：

1. 右键你的API项目 → 属性 → 生成 → 勾选“XML文档文件”，生成路径示例：bin\Debug\net6.0\YourApi.xml。
2. 在控制器类的注释里添加<summary>内容，同时确保控制器已绑定Tag：

/// <summary>
/// Access to customer information
/// </summary>
[ApiController]
[Route("api/customers")]
[ApiExplorerSettings(GroupName = "Customers")]
public class CustomersController : ControllerBase
{
    // ...
}

3. 在AddSwaggerGen中配置加载XML注释，并让Swashbuckle将控制器的摘要映射到Tag描述：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API标题", Version = "v1" });
    
    // 加载项目XML注释文件
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
    
    // 自定义Tag分组逻辑
    c.TagActionsBy(api =>
    {
        if (api.GroupName != null)
        {
            return new[] { api.GroupName };
        }
        
        // 默认按控制器名称分组，可按需调整
        var controllerName = api.ActionDescriptor.RouteValues["controller"];
        return new[] { controllerName };
    });
    
    c.EnableAnnotations();
});

配置完成后，控制器的<summary>内容就会自动作为对应Tag的描述出现在Swagger UI中。

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