如何在ASP.NET Core Swagger(Swashbuckle.AspNetCore)中设置控制器描述？

针对你遇到的Swagger控制器注释不生效，同时[ApiExplorerSettings]属性与版本分组冲突的问题，这里提供两种可行的解决方案：

方法一：在同一个ApiExplorerSettings属性中同时配置分组和显示名称 #

这是最直接的解决方案，无需额外代码，只需在控制器上修改[ApiExplorerSettings]属性，同时指定GroupName（版本分组）和DisplayName（控制器显示名称）即可：

/// <summary>
/// Uredsko poslovanje API
/// </summary>
[Authorize]
[Route("api/[controller]")]
[ApiExplorerSettings(GroupName = "v2", DisplayName = "Uredsko poslovanje API")] // 同时设置分组和显示名
public class UredskoPoslovanjeController : Controller
{
    private LinkDbContext ctx;
    public UredskoPoslovanjeController(LinkDbContext ctx) { this.ctx = ctx; }

    // 控制器方法代码...
}

这样既保留了API版本控制的分组需求，又能让Swagger UI显示你期望的控制器描述，完美解决属性冲突问题。

方法二：自定义IDocumentFilter自动读取控制器注释 #

如果你的项目中有多个控制器，不想手动为每个控制器添加DisplayName，可以通过自定义Swagger文档过滤器自动读取XML注释中的<summary>内容作为控制器显示名称，同时保留原有的版本分组：

1. 创建自定义文档过滤器 #

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Reflection;
using System.Xml.Linq;

public class ControllerSummaryDocumentFilter : IDocumentFilter
{
    private readonly XDocument _xmlDocumentation;

    public ControllerSummaryDocumentFilter(string xmlDocPath)
    {
        if (File.Exists(xmlDocPath))
        {
            _xmlDocumentation = XDocument.Load(xmlDocPath);
        }
    }

    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var apiDesc in context.ApiDescriptions)
        {
            // 获取控制器名称
            var controllerName = apiDesc.ActionDescriptor.RouteValues["controller"];
            // 构建XML注释中控制器的成员路径（替换成你的实际命名空间）
            var controllerMemberPath = $"T:{Assembly.GetExecutingAssembly().GetName().Name}.Controllers.{controllerName}Controller";
            
            // 查找对应的XML注释节点
            var controllerCommentNode = _xmlDocumentation?
                .Descendants("member")
                .FirstOrDefault(m => m.Attribute("name")?.Value == controllerMemberPath);

            if (controllerCommentNode != null)
            {
                var summaryNode = controllerCommentNode.Element("summary");
                if (summaryNode != null && !string.IsNullOrWhiteSpace(summaryNode.Value.Trim()))
                {
                    // 设置控制器显示名称，同时保留原有的版本分组
                    apiDesc.ActionDescriptor.DisplayName = summaryNode.Value.Trim();
                }
            }
        }
    }
}

2. 在Swagger配置中注册过滤器 #

首先确保你已经启用了XML注释生成：右键项目→属性→生成→勾选「XML文档文件」。然后在Program.cs（或Startup.cs）中配置Swagger时添加这个过滤器：

var builder = WebApplication.CreateBuilder(args);

// 注册Swagger服务
builder.Services.AddSwaggerGen(c =>
{
    // 配置Swagger文档信息
    c.SwaggerDoc("v2", new OpenApiInfo { Title = "你的API名称", Version = "v2" });
    
    // 获取XML注释文件路径
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    
    // 包含XML注释
    c.IncludeXmlComments(xmlFilePath);
    // 添加自定义文档过滤器
    c.DocumentFilter<ControllerSummaryDocumentFilter>(xmlFilePath);
});

var app = builder.Build();

// 启用Swagger中间件
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v2/swagger.json", "你的API v2");
    });
}

// 其他中间件配置...

app.Run();

注意事项 #

• 确保XML注释文件的生成路径正确，项目编译时能成功生成该文件；
• 方法二中的控制器成员路径需要匹配你实际的控制器命名空间，比如如果控制器在MyApi.Controllers下，要把T:{Assembly...}部分改成T:MyApi.Controllers.{controllerName}Controller；
• 两种方法都能保留原有的API版本分组功能，不会和GroupName设置冲突。

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