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

问题背景

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

典型场景示例

考虑以下ASP.NET Core控制器代码：

[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客户端时，会出现以下两种不同的行为：

旧版本行为（理想情况）：

getMessages(orderIdPath: number, 
    fromMessageId?: number | null | undefined, 
    cancelToken?: CancelToken): Promise<IGetMessagesResponse>

新版本行为（存在问题）：

getMessages(orderId: number, orderId?: number | undefined,  
    fromMessageId?: number | null | undefined, 
    cancelToken?: CancelToken): Promise<IGetMessagesResponse>

可以看到，新版本中出现了重复的orderId参数，这会导致TypeScript编译错误。

解决方案

1. 使用OpenApiIgnore属性

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

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

这样NSwag在生成TypeScript客户端时会忽略被标记的属性，避免参数重复。

2. 参数重命名

另一种解决方案是重命名其中一个参数，确保名称不冲突：

[HttpGet("Messages/{routeOrderId}")]
public async Task<ActionResult<GetMessagesResponse>> GetMessagesAsync(
    [FromRoute] int routeOrderId,
    [FromQuery] GetMessagesQuery request,
    CancellationToken cancellationToken)
{
    request.OrderId = routeOrderId;
    // ...
}

3. 自定义操作处理器

对于更复杂的情况，可以创建自定义的OperationProcessor来修改生成的OpenAPI规范：

public class RemoveDuplicateParametersOperationProcessor : IOperationProcessor
{
    public bool Process(OperationProcessorContext context)
    {
        var parameters = context.OperationDescription.Operation.Parameters;
        var seenParams = new HashSet<string>();
        
        for (int i = parameters.Count - 1; i >= 0; i--)
        {
            if (!seenParams.Add(parameters[i].Name))
            {
                parameters.RemoveAt(i);
            }
        }
        
        return true;
    }
}

然后在NSwag配置中注册这个处理器：

{
  "operationProcessors": [
    "RemoveDuplicateParametersOperationProcessor"
  ]
}

最佳实践建议

1. 保持参数名称唯一性：在设计API时，尽量避免路由参数和查询参数使用相同的名称。

2. 明确参数来源：使用[FromRoute]、[FromQuery]等属性明确指定参数来源，这有助于NSwag正确生成客户端代码。

3. 考虑使用DTO对象：对于复杂参数，考虑使用专门的DTO对象而不是基本类型，这样可以更好地控制生成的客户端代码。

4. 版本升级注意事项：在升级NSwag版本时，注意检查生成的客户端代码是否有重大变化，特别是参数处理部分。

总结

NSwag在生成TypeScript客户端时处理[FromRoute]和[FromQuery]参数重复的问题有多种解决方案。最简单直接的方法是使用[OpenApiIgnore]属性标记重复的属性。对于需要更精细控制的情况，可以考虑参数重命名或自定义操作处理器。在设计API时遵循最佳实践可以避免这类问题的发生。