Swashbuckle未填充路径参数及嵌套路由配置问题咨询

补充说明 #

经排查，问题出在Swagger（Swashbuckle）上，它未在URL中填充正确的customerId。本该发送请求到类似/api/customers/1/orders的地址，但实际发送的请求路径是字面意义的/api/customers/{customerid}/orders，并未将customerid替换为真实值。

请问如何配置才能让Swagger将真实值填充到URL中？

原问题 #

我有一个CustomersController和一个OrdersController。CustomersController的路由为/api/customers，是OrdersController路由（/api/customers/{customerId}/orders）的前缀。

[Route("api/[controller]")]
[ApiController]
public class CustomersController : ControllerBase
{
    [HttpGet]
    public async Task<IActionResult> List()
    {
        return Ok();
    }
}

[Route("api/customers/{customerId:int}/[controller]")]
[ApiController]
public class OrdersController : ControllerBase
{
    [HttpGet]
    public async Task<IActionResult> ListOrders(int customerId)
    {
        return Ok();
    }
}

Swagger页面（SwashBuckle）正确显示了这些API，但当我尝试调用/api/customers/{customerid}/orders时，返回404。该如何配置路由才能让API正常工作？

我想到一个临时解决方法，就是将ListOrders方法放到CustomersController中：

public class CustomersController : ControllerBase
{
    [HttpGet("{customerId:int}/orders")]
    public async Task<IActionResult> ListOrders(int customerId)
    {
        return Ok();
    }
}

但这并非我想要的方案，我希望CustomersController仅处理与customer相关的逻辑。

1. 修正路由定义（确保API本身可访问） #

当前OrdersController的路由[Route("api/customers/{customerId:int}/[controller]")]会生成/api/customers/{customerId:int}/orders，本身逻辑有效，但参数大小写不一致（路由参数是customerId，Swagger显示customerid）可能导致识别异常。建议直接指定路由后缀，避免[controller]的大小写问题，同时明确参数来源：

[Route("api/customers/{customerId:int}/orders")]
[ApiController]
public class OrdersController : ControllerBase
{
    [HttpGet]
    public async Task<IActionResult> ListOrders([FromRoute] int customerId)
    {
        return Ok();
    }
}

添加[FromRoute]可明确参数从路由中绑定，消除模型绑定歧义。

2. 配置Swashbuckle识别并填充路由参数 #

方式一：启用XML注释优化参数识别 #

在Program.cs（或Startup.cs）的Swagger配置中启用XML注释，帮助Swagger更准确识别参数信息：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    // 引入项目XML注释文件（需在项目属性中启用XML文档生成）
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

启用后，还可以给参数添加注释，让Swagger展示更清晰的提示：

/// <summary>
/// 获取指定客户的订单列表
/// </summary>
/// <param name="customerId">客户ID</param>
[HttpGet]
public async Task<IActionResult> ListOrders([FromRoute] int customerId)
{
    return Ok();
}

方式二：自定义过滤器强制处理路由参数 #

如果自动识别仍有问题，可通过IOperationFilter自定义参数规则，强制标记路由参数为必填并设置默认值：

public class RouteParameterFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var routeParams = context.ApiDescription.ParameterDescriptions
            .Where(p => p.Source == BindingSource.Path)
            .ToList();

        foreach (var param in routeParams)
        {
            var openApiParam = operation.Parameters.FirstOrDefault(p => p.Name == param.Name);
            if (openApiParam != null)
            {
                openApiParam.Required = true;
                openApiParam.Example = new OpenApiInteger(1); // 设置默认测试值
            }
        }
    }
}

然后在Swagger配置中注册该过滤器：

builder.Services.AddSwaggerGen(c =>
{
    // ...其他配置
    c.OperationFilter<RouteParameterFilter>();
});

3. 验证效果 #

重启项目后访问Swagger页面：

• Orders的API会显示customerId输入框（或已填充默认值1）
• 输入真实客户ID调用时，请求路径会自动替换为/api/customers/xxx/orders，不再包含占位符，即可正常返回结果。

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