NSwag中处理FromRoute和FromQuery参数重复问题的解决方案

问题背景

在使用NSwag生成TypeScript客户端时，当ASP.NET Core控制器方法同时使用[FromRoute]和[FromQuery]属性时，可能会遇到参数重复的问题。这种情况通常发生在路由参数和查询参数包含相同名称的属性时。

典型场景分析

考虑以下控制器方法示例：

[HttpGet("Messages")]
public async Task<ActionResult<GetMessagesResponse>> GetMessagesAsync(
    [FromRoute] int orderId,
    [FromQuery] GetMessagesQuery request,
    CancellationToken cancellationToken)
{
    request.OrderId = orderId;
    return Ok(await Sender.Send(request, cancellationToken));
}

其中GetMessagesQuery类定义如下：

public class GetMessagesQuery 
{
    public int OrderId { get; set; }
    public int? FromMessageId { get; set; }
}

参数重复问题表现

在NSwag生成TypeScript客户端时，会出现以下情况：

1. 理想情况：[FromRoute]的orderId应被命名为orderIdPath，而查询对象中的OrderId属性应被忽略
2. 问题情况：生成的方法签名中会出现重复的orderId参数

// 问题代码示例
getMessages(
    orderId: number, 
    orderId?: number | undefined,  // 重复参数
    fromMessageId?: number | null | undefined,
    cancelToken?: CancelToken
): Promise<IGetMessagesResponse>

解决方案

使用OpenApiIgnore属性

最直接的解决方案是在查询对象中使用[OpenApiIgnore]属性标记重复的属性：

public class GetMessagesQuery 
{
    [OpenApiIgnore]
    public int OrderId { get; set; }
    public int? FromMessageId { get; set; }
}

这样NSwag在生成客户端代码时会忽略被标记的属性，从而避免参数重复问题。

其他可选方案

1. 参数重命名：修改控制器方法或查询对象中的参数名称，确保没有重复
2. 自定义操作处理器：实现自定义的IOperationProcessor来处理参数生成逻辑
3. 使用不同的参数来源：考虑将重复参数统一从路由或查询中获取，而不是两者都使用

最佳实践建议

1. 在设计API时，尽量避免路由参数和查询参数使用相同的名称
2. 对于必须使用相同名称的场景，优先使用[OpenApiIgnore]解决方案
3. 在团队中建立统一的参数命名规范，减少此类问题的发生
4. 定期检查NSwag生成的客户端代码，确保没有意外的参数重复

总结

NSwag作为强大的API客户端生成工具，在处理复杂参数场景时可能会遇到参数重复问题。通过合理使用[OpenApiIgnore]属性或调整API设计，可以有效地解决这类问题，确保生成的TypeScript客户端代码清晰、正确且易于使用。