Swagger参数前缀“query.”问题：原理与解决指南

有前端同事发来一张 Swagger 页面截图，问我：“Search 这两个接口的参数名怎么变成 query.customerName、query.pageIndex 了？之前不是说好传 customerName 和 pageIndex 吗？”

我一看，典型的老项目在 ASP.NET Core 里用 Swashbuckle 生成 API 文档时遇到的参数前缀问题。参数本身没写错，请求也能调到后端，但 Swagger UI 上暴露出来的参数名带了一个 query. 前缀，前端照着文档传参会觉得非常别扭，后端排查时也容易被误导。

这篇文章就围绕 Swashbuckle 中的参数前缀问题展开，把这个现象的原理、复现方式、以及我用过的几种解决方案完整梳理一遍。适合正在做 .NET API 开发、被 Swagger 文档参数显示问题困扰的开发者，不管你是刚接触 Swashbuckle，还是已经在老项目里被它磨了好几天，都能从中找到可落地的处理思路。

1. 复现：Swagger 页面里每个查询参数都多了个 query.

1.1 一个典型场景：查询条件对象

先说下我最初遇到这个问题时的代码。一个标准的订单查询接口，因为筛选条件比较多，封装了一个查询对象：

csharp复制public class OrderQuery
{
    public string CustomerName { get; set; }
    public DateTime? StartDate { get; set; }
    public DateTime? EndDate { get; set; }
    public int PageIndex { get; set; } = 1;
    public int PageSize { get; set; } = 20;
}

[ApiController]
[Route("api/orders")]
public class OrdersController : ControllerBase
{
    [HttpGet]
    public IActionResult Search([FromQuery] OrderQuery query)
    {
        // 实际查询逻辑省略
        return Ok();
    }
}

这个写法很常见：参数多了，用一个 DTO 聚合起来，[FromQuery] 表示从 QueryString 绑定。项目里用的 Swashbuckle 版本是 4.x，生成出来的 Swagger 文档里，接口参数变成了下面这个样子：

每个参数前面都带着 query. 这个前缀。前端同事看到这个文档的第一反应是：接口参数名是不是改名了？但实际后端逻辑完全没变，用手工的 ?query.customerName=xxx 去请求，也能正常拿到数据。

再换成 Swashbuckle 5.x 或 6.x，现象又不一样：Swagger UI 里不再展开成多个带前缀的参数，而是只显示一个名为 query 的对象参数，展开后是一整个 schema 的 JSON 编辑框，同样很难受。

1.2 前缀不是乱码，它就是方法参数名本身

这里的 query 其实就是 action 方法里的参数名。Swashbuckle 在生成文档时，会把“参数名.属性名”拼接在一起，作为对外暴露的参数名称。

在 ASP.NET Core 的模型绑定体系里，这种带点号的名称是有实际意义的。query.customerName 表示“名字为 query 的模型对象上的 customerName 属性”。后端绑定器拿到这个 key 之后，会自动把值注入到 OrderQuery.CustomerName 上。所以这个前缀不是 Swashbuckle 自己拍脑袋加出来的乱码，而是运行时模型绑定的真实规则。

可以类比成数据库 SQL 里的表别名：a.id、a.name 里的 a 是表别名。如果只有一张表，写 id、name 也能查出结果，但如果联表查询且多张表都有同名字段，别名就变成了强制要求。Swagger 里的 query. 前缀也是同样的作用，只是当查询对象只有一个、字段又不冲突时，这个前缀就显得多余了。

2. 前缀从哪来：ApiExplorer 与 OpenAPI 的展开逻辑

2.1 ApiExplorer 如何描述查询参数

Swashbuckle 生成 Swagger 文档并不是自己把每个 action 反射一遍然后猜参数，它是消费 ASP.NET Core MVC 的 ApiExplorer 结果。

ApiExplorer 在框架里负责把 Controller、Action、参数这些运行时信息，翻译成 ApiDescription。其中每个参数对应一个 ApiParameterDescription，它有一个 Name 属性，这个 Name 不是简单的方法参数名，而是模型绑定器最终用来从请求里取值的完整 key。

对 [FromQuery] OrderQuery query 这种复杂类型参数来说，ASP.NET Core 在生成 ApiParameterDescription 的时候，会按“参数名 + 属性名”的方式展开。于是 query.customerName、query.pageIndex 就作为独立的参数名出现了。Swashbuckle 拿到的数据源里已经有了这个前缀，所以它只是把这个 Name 原样渲染到了 Swagger 文档上。

所以你可以理解为：Swashbuckle 在这件事上基本是无辜的。它不是故意加前缀，而是把它看到的 ApiParameterDescription.Name 显示出来了。

2.2 Swagger 2.0 和 OpenAPI 3.0 的展示差异

不同版本的 Swashbuckle 对这个前缀的最终呈现形式还不一样，这和 Swagger 规范版本有关。

Swashbuckle 4.x 使用的是 Swagger 2.0 规范。Swagger 2.0 对 query 参数不支持“对象类型”这种表达方式，只能把所有字段拆成独立的 query 参数。所以 ApiExplorer 里生成的 query.customerName、query.pageIndex，会被直接当成参数名写进文档。

Swashbuckle 5.x 和 6.x 使用的是 OpenAPI 3.0 规范。OpenAPI 3.0 支持把 query 参数定义成一个对象，比如 name=query、schema 指向 OrderQuery 对象。所以 Swashbuckle 不再把字段全部拆开，而是合并成一个整体对象参数。Swagger UI 打开后，你会看到一个名为 query 的参数，点开它能看到完整的对象结构。

这两种呈现形式各有各的别扭：

搞清楚这个差异之后，解决问题的方式就会清晰很多：要么在源头控制模型绑定名称，要么在 Swashbuckle 生成文档之后做一层参数名修正。

3. 方案一：拍平查询参数，让文档和绑定都扁平化

3.1 直接改方法签名的做法

最笨、但最可靠的方法，就是不用查询对象，把 action 的参数拍平成简单类型。

csharp复制[HttpGet]
public IActionResult Search(
    [FromQuery] string customerName,
    [FromQuery] DateTime? startDate,
    [FromQuery] DateTime? endDate,
    [FromQuery] int pageIndex = 1,
    [FromQuery] int pageSize = 20)
{
    var query = new OrderQuery
    {
        CustomerName = customerName,
        StartDate = startDate,
        EndDate = endDate,
        PageIndex = pageIndex,
        PageSize = pageSize
    };

    // 后续逻辑不变
    return Ok();
}

这样一来，Swagger 文档里生成的参数名就变成了 customerName、startDate、endDate、pageIndex、pageSize，前缀完全消失。运行时模型绑定拿到的也是这些参数名，不需要任何额外过滤器去修正。

3.2 拍平方案适合什么场景

我一般建议，如果查询参数不超过 10 个，优先拍平。理由很简单：文档即事实，前端看文档写代码，不会产生歧义。

参数不多的时候，拍平也不会让方法签名变得有多难看。如果担心方法参数太多，可以在 action 内部立刻组装成 OrderQuery 对象，后续传给 Service 层时仍然使用你熟悉的 DTO，对业务代码没有任何侵入。

还有一种做法是给每个参数显式指定对外名称：

csharp复制[FromQuery(Name = "customerName")] string customerName

这适合那些希望对外参数名保持某个固定风格，但内部变量名想更简洁的场景。比如外部文档要求 CustomerName 大驼峰，内部参数名写成 customerName 小驼峰，用 Name 属性转换即可。

拍平方案的缺点是：当查询对象字段特别多、或者会被多个接口复用时，方法签名会变得极长，维护成本上升。这种情况下就需要用下面的方案。

4. 方案二：OperationFilter 去前缀，不改接口签名

4.1 Swashbuckle 4.x：给参数名做手术

如果不想动接口签名，另一个思路是在 Swashbuckle 生成文档之后，用 IOperationFilter 把参数名里的前缀去掉。

Swashbuckle 4.x 时代，参数名是 query.customerName 这种带点号的字符串，直接在过滤器里截断即可。5.x/6.x 的写法在 OpenApiOperation 上略微不同，但思路一致。以下代码以 5.x/6.x 的 API 形态演示，4.x 的本质上也是找参数、改名这两步：

csharp复制using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public class RemoveQueryPrefixOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null)
        {
            return;
        }

        foreach (var parameter in operation.Parameters
                     .Where(p => p.In == ParameterLocation.Query)
                     .ToList())
        {
            var dotIndex = parameter.Name.IndexOf('.');
            if (dotIndex > 0)
            {
                parameter.Name = parameter.Name.Substring(dotIndex + 1);
            }
        }
    }
}

注册方式：

csharp复制services.AddSwaggerGen(c =>
{
    c.OperationFilter<RemoveQueryPrefixOperationFilter>();
});

这段代码对于 4.x 生成的 query.customerName 会直接改成 customerName，而对于 5.x/6.x 中一个对象参数的情况，因为没有点号，所以不会动手。

4.2 Swashbuckle 5/6：把对象参数展开成一组参数

到了 Swashbuckle 5.x/6.x，query 参数不再展开，而是一个 OpenApiParameter，它的 Schema 指向 OrderQuery 的 schema 引用。这时去点号没有用，因为参数名本身没有点号。

我采用的办法是写一个专门的 OperationFilter，把这个对象参数从 operation.Parameters 里摘掉，然后去 SchemaRepository 中找到对应的 schema 属性，逐个生成独立的 query 参数，让 UI 重新变回扁平的输入框。

csharp复制using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public class ExpandQueryObjectOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null)
        {
            return;
        }

        var queryParameters = operation.Parameters
            .Where(p => p.In == ParameterLocation.Query)
            .ToList();

        foreach (var parameter in queryParameters)
        {
            var referenceId = parameter.Schema?.Reference?.Id;
            if (referenceId == null)
            {
                continue;
            }

            if (!context.SchemaRepository.Schemas.TryGetValue(referenceId, out var schema))
            {
                continue;
            }

            operation.Parameters.Remove(parameter);

            foreach (var property in schema.Properties)
            {
                operation.Parameters.Add(new OpenApiParameter
                {
                    Name = property.Key,
                    In = ParameterLocation.Query,
                    Required = schema.Required?.Contains(property.Key) ?? false,
                    Schema = property.Value
                });
            }
        }
    }
}

这段代码的核心逻辑是：先确认这个 query 参数确实是一个对象引用，再去 SchemaRepository 里找到它对应的 schema，最后把对象的每个属性变成独立的 query 参数。参数名取的是属性名，不再有 query. 前缀。

注册方式跟前面一样，在 AddSwaggerGen 里加一行 c.OperationFilter<ExpandQueryObjectOperationFilter>(); 即可。

4.3 去前缀操作的边界条件

过滤器方案