如何让Swagger从XML注释获取自定义IRouteConstraint的参数描述？

首先得明确：默认情况下Swashbuckle（.NET生态里常用的Swagger实现）并没有内置能力直接从XML注释中提取自定义IRouteConstraint关联的路由参数描述。原因很简单：路由约束是路由定义层面的配置，而XML注释主要绑定到控制器动作、动作参数、模型类型上，两者之间没有预设的映射逻辑，所以Swagger不知道该把哪段注释对应到带约束的路由参数上。

不过你也不用一直依赖硬编码的OperationFilter，这里有几个更优雅的优化方案：

方案1：利用控制器XML注释的<remarks>标签+通用OperationFilter #

如果你的路由绑定到控制器/动作，可以在控制器的XML注释里，用<remarks>块专门标注路由参数的说明，然后写一个通用的OperationFilter来解析这段内容，自动同步到Swagger的参数描述中。

比如控制器的XML注释可以这么写：

/// <summary>
/// 获取指定类型的资源列表
/// </summary>
/// <remarks>
/// 路由参数说明：
/// - resourceType: 自定义类型约束，仅允许传入"user"、"order"或"product"
/// </remarks>
/// <returns>资源列表</returns>
[Route("api/resources/{resourceType:myCustomTypeConstraint}")]
public IActionResult GetResources()
{
    // 业务逻辑
}

然后写一个OperationFilter，遍历Swagger的每个Operation，解析对应控制器/动作的XML注释里的<remarks>内容，匹配路由参数名，把对应的描述赋值给Swagger参数。这种方式不用每次新增约束都修改Filter的硬编码逻辑，维护起来更灵活。

方案2：给路由参数附加元数据+元数据读取Filter #

在注册路由的时候，给带约束的参数附加自定义元数据，然后用OperationFilter读取这些元数据来设置Swagger描述。

比如注册路由时：

// 先定义一个元数据类
public class RouteParamDescriptionMetadata
{
    public string ParamName { get; set; }
    public string Description { get; set; }
}

// 注册路由时附加元数据
app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "customResource",
        pattern: "api/resources/{resourceType:myCustomTypeConstraint}",
        defaults: new { controller = "Resource", action = "GetResources" },
        constraints: new { resourceType = new MyCustomTypeConstraint() },
        metadata: new List<object>
        {
            new RouteParamDescriptionMetadata 
            { 
                ParamName = "resourceType", 
                Description = "自定义类型约束，仅允许传入'user'、'order'或'product'" 
            }
        }
    );
});

然后写一个OperationFilter，获取当前路由的元数据集合，找到RouteParamDescriptionMetadata实例，对应设置Swagger参数的描述。这种方式把参数描述和路由定义放在一起，逻辑更清晰。

方案3：属性路由+动作参数绑定（如果适用） #

如果你的路由参数同时也是动作方法的参数，那直接给动作参数加XML注释即可，Swagger会自动把注释关联到路由参数上。比如：

/// <summary>
/// 获取指定类型的资源列表
/// </summary>
/// <param name="resourceType">自定义类型约束，仅允许传入"user"、"order"或"product"</param>
/// <returns>资源列表</returns>
[Route("api/resources/{resourceType:myCustomTypeConstraint}")]
public IActionResult GetResources(string resourceType)
{
    // 业务逻辑
}

这种情况下，Swagger会自动把resourceType参数的XML注释显示在路由参数的描述区域，完全不需要额外的Filter。当然，这个方案只适用于路由参数需要传入动作方法的场景。

总的来说，目前没有开箱即用的“直接读取IRouteConstraint注释”的功能，但通过上述方案可以避免硬编码的OperationFilter，让注释维护更高效。

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