如何为ASP.NET Core控制器路由模板的Mandator参数添加Swagger描述？

目前ASP.NET Core没有原生的类级别特性直接为路由模板参数添加XML描述，但可以通过以下两种方式实现需求：

方法一：自定义Swagger操作过滤器解析XML注释 #

1. 启用XML文档生成
   在项目属性的“生成”选项卡中，勾选“生成XML文档文件”，并记下生成的XML文件路径（通常位于输出目录下）。

2. 在控制器注释中添加参数描述
   在控制器的摘要注释里加入<param>标签，指定路由参数的描述：

/// <summary>
/// 程序集管理接口
/// <param name="Mandator">租户唯一标识，用于路由区分不同租户实例</param>
/// </summary>
[Route("{Mandator}/api/[controller]")]
[ApiController]
public class AssemblyController : ControllerBase
{
    // 接口实现代码
}

3. 创建自定义操作过滤器
   编写过滤器读取XML注释中的<param>标签，并将描述绑定到Swagger的路由参数上：

public class RouteParamDescriptionFilter : IOperationFilter
{
    private readonly XDocument _xmlDoc;

    public RouteParamDescriptionFilter(string xmlFilePath)
    {
        if (File.Exists(xmlFilePath))
        {
            _xmlDoc = XDocument.Load(xmlFilePath);
        }
    }

    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var controllerType = context.ControllerType;
        var xmlNodePath = $"//member[@name='T:{controllerType.FullName}']";
        var controllerXmlNode = _xmlDoc?.XPathSelectElement(xmlNodePath);

        if (controllerXmlNode == null) return;

        foreach (var paramNode in controllerXmlNode.Descendants("param"))
        {
            var paramName = paramNode.Attribute("name")?.Value;
            var paramDesc = paramNode.Value.Trim();

            var targetParam = operation.Parameters?.FirstOrDefault(p => 
                p.Name == paramName && p.In == ParameterLocation.Path);
            
            if (targetParam != null)
            {
                targetParam.Description = paramDesc;
            }
        }
    }
}

4. 注册过滤器到Swagger服务
   在Program.cs中配置Swagger时，添加这个自定义过滤器：

var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);

builder.Services.AddSwaggerGen(options =>
{
    options.IncludeXmlComments(xmlFilePath);
    options.OperationFilter<RouteParamDescriptionFilter>(xmlFilePath);
});

方法二：通过控制器属性绑定Swagger参数描述 #

在控制器中定义与路由参数同名的属性，并用[SwaggerParameter]标记描述：

[Route("{Mandator}/api/[controller]")]
[ApiController]
public class AssemblyController : ControllerBase
{
    [SwaggerParameter("租户唯一标识，用于区分不同租户实例", Required = true)]
    [FromRoute]
    public string Mandator { get; set; }

    // 接口实现代码
}

这种方式无需额外编写过滤器，Swagger会自动读取[SwaggerParameter]中的描述并展示在UI上。

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