如何让Swagger为.NET Core API生成正确的路径参数请求URL？

问题场景 #

我有一个.NET Core API，接收字符串、两个日期和整数类型的路径参数，本地部署后的URL格式为：

https://localhost/api/v2/TimeSeries/<id>/<from-date>/<to-date>/<int-value>

控制器定义如下：

[HttpGet("{id}/{from:datetime}/{to:datetime}/{resolution:int}")]
[ApiExplorerSettings(GroupName = "v2")]
public async Task<IActionResult> IndexAsync([FromRoute] Query query) 
                                  => Ok(await _mediator.Send(query));

该API通过Postman调用可正常返回结果，但使用Swagger测试时，点击Execute后生成的URL未替换带大括号的参数名，导致请求出现404错误。

解决方案 #

1. 确保模型属性与路由参数名完全匹配 #

Swagger需要明确的参数映射关系，首先检查你的Query模型属性名称是否和路由中的参数名完全一致（区分大小写）：

public class Query
{
    public string Id { get; set; }
    public DateTime From { get; set; }
    public DateTime To { get; set; }
    public int Resolution { get; set; }
}

2. 显式绑定参数名称（若属性名与路由名不一致） #

如果模型属性名和路由参数名不同，需要给每个属性添加[FromRoute(Name = "路由参数名")]特性，强制映射关联：

public class Query
{
    [FromRoute(Name = "id")]
    public string TimeSeriesId { get; set; }
    [FromRoute(Name = "from")]
    public DateTime FromDate { get; set; }
    [FromRoute(Name = "to")]
    public DateTime ToDate { get; set; }
    [FromRoute(Name = "resolution")]
    public int Interval { get; set; }
}

3. 检查Swagger配置完整性 #

在Program.cs（或旧版本的Startup.cs）中，确认Swagger配置包含必要的元数据支持，比如XML注释（可选但有助于参数识别）：

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

4. 临时排查：改用单个参数绑定 #

如果以上方法无效，可以暂时改用单个参数接收路由值，再手动构建Query对象，验证Swagger是否能正常识别参数：

[HttpGet("{id}/{from:datetime}/{to:datetime}/{resolution:int}")]
[ApiExplorerSettings(GroupName = "v2")]
public async Task<IActionResult> IndexAsync(
    [FromRoute] string id, 
    [FromRoute] DateTime from, 
    [FromRoute] DateTime to, 
    [FromRoute] int resolution)
{
    var query = new Query { Id = id, From = from, To = to, Resolution = resolution };
    return Ok(await _mediator.Send(query));
}

问题原因 #

Swagger依赖API元数据生成交互文档，当使用复杂模型接收路由参数时，若没有明确的属性-参数映射关系，Swagger无法将模型属性与路由占位符关联，导致生成请求时无法替换{id}、{from}等占位符，最终请求无效URL引发404。

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