C# ASP.Net中Get API传JSON对象为查询参数时Swagger报错如何解决

AI 小北

2026-9-24

问题根因

ASP.NET Core 对复杂类型参数（如自定义的Filter类）默认绑定源为[FromBody]，而HTTP规范明确禁止GET/HEAD类型的请求携带请求体，因此SwaggerUI发起调用时会触发Request with GET/HEAD method cannot have body报错。
添加[FromQuery]后出现的歧义调用错误，通常由两类原因导致：一是当前Controller下存在路由、参数签名高度相似的接口，触发路由匹配歧义；二是Swagger的Schema生成规则未适配复杂类型的查询字符串绑定逻辑。

解决方案

修正接口参数绑定配置
仅给自定义复杂类型显式添加[FromQuery]特性即可，CancellationToken会被框架自动识别注入，不需要额外加绑定特性：
```
// GET: api/user/list
[HttpGet("list")]
public async Task<IActionResult> GetUsers(CancellationToken cancellationToken, [FromQuery] Filter options = null)
{
    // 业务逻辑实现
}
```
如果修改后仍报歧义调用，检查当前Controller下所有接口的路由配置，不能存在HTTP方法、路由路径完全一致的接口重载，可通过修改重复接口的路由，或者给不需要暴露到Swagger的接口添加[ApiExplorerSettings(IgnoreApi = true)]特性隐藏即可。
适配Swagger的OpenAPI配置
若使用Swashbuckle.AspNetCore包，在服务注册部分添加如下配置，支持复杂类型的查询参数生成：
```
builder.Services.AddSwaggerGen(c =>
{
    // 保留原有Swagger配置，新增以下规则
    c.UseAllOfToExtendReferenceSchemas();
    c.MapType<Filter>(() => new OpenApiSchema { Type = "object" });
});
```
若之前使用的是OpenAPI 2.0规范，升级到3.0只需确保SwaggerDoc配置正常即可，Swashbuckle 5.x以上版本默认使用OpenAPI 3.0规范。
校验Filter类结构
确保Filter类的所有属性都是字符串、数值、布尔、枚举等基础类型，如果存在嵌套复杂类型，需要自定义查询字符串绑定器，或者将嵌套属性扁平化到Filter的一级属性，否则查询字符串无法完成嵌套对象的绑定。