如何配置查询字符串数组参数为style=form、explode=false并适配Swagger生成

数组参数绑定实现 #

内置支持说明 #

ASP.NET Core 6及以上版本已经提供了轻量化的自定义绑定能力，无需额外引入第三方包即可实现逗号分隔查询参数的解析，你可以选择两种实现方案：

• 单参数快速处理：直接将参数声明为string类型，接收后手动调用Split(',')拆分得到数组，适合临时的小范围使用场景
• 通用绑定方案：实现自定义TypeConverter，注册后可以直接给参数或者模型属性添加特性生效，示例代码如下：

[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property)]
public class CommaSeparatedQueryAttribute : TypeConverterAttribute
{
    public CommaSeparatedQueryAttribute() : base(typeof(CommaSeparatedStringArrayConverter)) { }

    private class CommaSeparatedStringArrayConverter : TypeConverter
    {
        public override bool CanConvertFrom(ITypeDescriptorContext context, Type sourceType)
        {
            return sourceType == typeof(string) || base.CanConvertFrom(context, sourceType);
        }

        public override object ConvertFrom(ITypeDescriptorContext context, CultureInfo culture, object value)
        {
            if (value is string inputStr)
            {
                return inputStr.Split(',', StringSplitOptions.RemoveEmptyEntries);
            }
            return base.ConvertFrom(context, culture, value);
        }
    }
}

使用时直接在接口参数上添加特性即可：

public IActionResult GetList([CommaSeparatedQuery] [FromQuery] IEnumerable<string> id)
{
    // 这里的id会自动解析逗号分隔的查询字符串
    return Ok(id);
}

Swagger配置实现 #

要让Swagger正确识别逗号分隔的数组参数，只需要给Swashbuckle添加自定义操作过滤器，识别我们上面定义的CommaSeparatedQueryAttribute，自动修改参数的序列化配置即可，步骤如下：

1. 实现IOperationFilter

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public class CommaSeparatedQuerySwaggerFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 找到所有带CommaSeparatedQueryAttribute的参数
        var targetParams = context.MethodInfo.GetParameters()
            .Where(p => p.GetCustomAttribute<CommaSeparatedQueryAttribute>() != null)
            .ToList();

        foreach (var param in targetParams)
        {
            var swaggerParam = operation.Parameters.FirstOrDefault(p => 
                p.Name.Equals(param.Name, StringComparison.OrdinalIgnoreCase) 
                && p.In == ParameterLocation.Query);
            if (swaggerParam != null)
            {
                swaggerParam.Style = ParameterStyle.Form;
                swaggerParam.Explode = false;
            }
        }
    }
}

2. 在Swagger配置中注册过滤器

builder.Services.AddSwaggerGen(opt =>
{
    // 其他Swagger配置
    opt.OperationFilter<CommaSeparatedQuerySwaggerFilter>();
});

完成配置后，所有加了CommaSeparatedQueryAttribute的数组查询参数都会自动按照style=form、explode=false的规则生成Swagger文档，测试时也会自动按逗号分隔的格式拼接参数。

如果你需要全局生效，不需要加特性，直接修改过滤器的判断逻辑，只要是查询参数且类型实现了IEnumerable接口，就自动设置Explode=false即可。

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