.NET Core 7扩展Swagger支持自定义HTTP方法及长查询替代方案

一、扩展Swagger支持QUERY自定义HTTP方法 #

Swashbuckle默认仅识别标准HTTP方法，要让Swagger UI正确渲染QUERY端点，需从操作过滤器、文档过滤器、UI自定义脚本三个层面做扩展：

1. 定义QUERY方法特性 #

先创建标记QUERY请求的自定义特性：

public class HttpQueryAttribute : HttpMethodAttribute
{
    public HttpQueryAttribute() : base(new[] { "QUERY" }) { }
}

2. 实现操作过滤器识别QUERY方法 #

通过操作过滤器标记对应接口的请求方法为QUERY：

public class QueryHttpMethodOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var queryAttr = context.MethodInfo.GetCustomAttributes(true)
            .OfType<HttpQueryAttribute>()
            .FirstOrDefault();

        if (queryAttr != null)
        {
            operation.Method = "QUERY";
            operation.Summary = operation.Summary ?? "QUERY 查询请求";
        }
    }
}

3. 文档过滤器注册QUERY到Swagger规范 #

确保Swagger文档能将QUERY识别为合法请求方法：

public class QueryHttpMethodDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var pathEntry in swaggerDoc.Paths)
        {
            var path = pathEntry.Value;
            var queryOperations = path.Operations
                .Where(op => op.Value.Method == "QUERY")
                .ToList();

            foreach (var op in queryOperations)
            {
                var operationType = (OperationType)Enum.Parse(typeof(OperationType), "Query", ignoreCase: true);
                path.Operations.Add(new KeyValuePair<OperationType, OpenApiOperation>(operationType, op.Value));
            }
        }
    }
}

4. 配置Swagger并注入UI自定义脚本 #

在Program.cs中注册过滤器，并添加自定义JS让Swagger UI显示QUERY按钮：

// 注册Swagger生成器
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "自定义API", Version = "v1" });
    c.OperationFilter<QueryHttpMethodOperationFilter>();
    c.DocumentFilter<QueryHttpMethodDocumentFilter>();
});

// 配置Swagger UI
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "自定义API V1");
    // 注入自定义脚本扩展UI
    c.InjectJavascript("/swagger-custom.js");
});

创建wwwroot/swagger-custom.js文件，将QUERY添加到UI支持的方法列表：

window.addEventListener('load', function() {
    const ui = window.ui;
    const supportedMethods = ui.getConfig().supportedSubmitMethods;
    
    if (!supportedMethods.includes('query')) {
        supportedMethods.push('query');
        ui.updateSpec();
    }
});

完成以上配置后，Swagger UI即可正常渲染QUERY方法的端点并支持调试调用。

二、不修改应用设置的长查询GET替代方案 #

若不想扩展Swagger，以下两种方案无需修改服务器配置即可解决长查询问题：

1. 用POST请求模拟查询语义 #

设计专门的查询端点，将长查询参数放在请求体中，用POST方法传递，同时保持查询语义（返回200 OK及查询结果）。示例：

[HttpPost("api/products/query")]
public IActionResult QueryProducts([FromBody] ProductQueryDto queryDto)
{
    // 执行查询逻辑
    var result = _productService.Search(queryDto);
    return Ok(result);
}

// 查询参数DTO
public class ProductQueryDto
{
    public string[] Categories { get; set; }
    public decimal? MinPrice { get; set; }
    public string SearchKeyword { get; set; }
    // 其他长查询参数
}

这种方式完全绕过URL长度限制，只需在接口文档中明确标注该POST用于查询操作即可。

2. 查询参数序列化到请求头（应急方案） #

将长查询参数序列化为JSON后放到自定义请求头（如X-Query-Params）中，后端读取后反序列化处理。但该方式不符合REST规范，可读性差，且部分网关可能限制请求头大小，仅作为临时备选。

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