如何在.NET 6的Swagger中发送查询参数数组的空字符串？

问题分析 #

启用SupportNonNullableReferenceTypes()后，Swagger默认会对可空字符串类型（string?）的输入做严格校验，导致UI中无法输入空字符串，只能通过留空发送null。要解决这个问题，需要同时调整Swagger的Schema生成规则，确保ASP.NET Core的模型绑定能正确接收空字符串。

解决方案步骤 #

1. 确保控制器参数绑定支持空字符串 #

控制器方法保持现有定义，可显式添加[FromQuery]特性明确绑定来源，避免模型绑定把空字符串自动转为null：

[HttpGet("look-up-before-create")]
public IActionResult LookUpBeforeCreate(
    [FromQuery] IEnumerable<Guid> attr, 
    [FromQuery] IEnumerable<string?> val)
{
    // 业务逻辑实现
    return Ok();
}

2. 配置Swagger允许空字符串输入 #

在Program.cs的Swagger配置中，添加自定义Schema过滤器，修改string?类型的Schema设置，允许空值和空字符串：

builder.Services.AddSwaggerGen(options =>
{
    options.SupportNonNullableReferenceTypes();

    // 注册自定义Schema过滤器处理可空字符串
    options.SchemaFilter<NullableStringSchemaFilter>();
});

// 自定义Schema过滤器类
public class NullableStringSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 处理单个可空字符串或可空字符串数组
        var targetType = context.Type;
        if (targetType == typeof(string?) || 
            (targetType.IsGenericType && 
             targetType.GetGenericTypeDefinition() == typeof(IEnumerable<>) && 
             targetType.GetGenericArguments()[0] == typeof(string?)))
        {
            // 标记为允许空值
            schema.Nullable = true;
            // 设置空字符串为示例值，引导UI允许输入空内容
            schema.Example = new OpenApiString("");

            // 如果是数组类型，同步调整元素的Schema规则
            if (schema.Type == "array" && schema.Items != null)
            {
                schema.Items.Nullable = true;
                schema.Items.Example = new OpenApiString("");
            }
        }
    }
}

3. 可选：调整Swagger UI输入限制 #

如果上述配置后UI仍限制空字符串输入，可在Swagger UI配置中添加额外参数放宽限制：

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    // 允许UI输入空值内容
    options.ConfigObject.AdditionalItems.Add("allowEmptyValue", true);
});

验证效果 #

配置完成后重启项目，进入Swagger页面测试：

• val参数的数组元素输入框可直接输入空字符串，控制器能正常接收该空字符串元素
• 留空元素输入框可发送null值
• attr参数仍保持必填规则，仅接受有效Guid格式的输入

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