ASP.NET Core 8.0上传端点用IFormFile遇Swagger及Postman错误求助

问题现象 #

开发ASP.NET Core 8.0 Web API的Excel文件上传端点时，遇到两个核心问题：

1. Swagger无法加载，抛出生成错误
2. Postman通过multipart/form-data发送文件时，返回400校验错误

Swagger加载错误 #

Swashbuckle.AspNetCore.SwaggerGen.SwaggerGeneratorException: Error reading parameter(s) for action WebApi.Controllers.LocationsController.UploadFile (WebApi) as [FromForm] attribute used with IFormFile. Please refer to https://github.com/domaindrivendev/Swashbuckle.AspNetCore#handle-forms-and-file-uploads for more information

Postman请求错误 #

{
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": { "file": ["The file field is required."] }
}

控制器代码 #

[HttpPost("upload")]
[RequestSizeLimit(104857600)] // 限制请求大小为100MB
public async Task<IActionResult> UploadFile([FromForm] IFormFile file)
{
    var validationMessage = UploadHandler.ValidateFile(file);
    if (!string.IsNullOrEmpty(validationMessage))
        return BadRequest(validationMessage);

    try
    {
        using var stream = new MemoryStream();
        await file.CopyToAsync(stream);

        using var package = new ExcelPackage(stream);
        var worksheet = package.Workbook.Worksheets.FirstOrDefault();
        if (worksheet == null)
            return BadRequest("Invalid Excel file.");

        var locations = new List<Location>();
        for (int row = 2; row <= worksheet.Dimension.End.Row; row++) // 从第2行开始跳过表头
        {
            var location = new Location
            {
                WhId = worksheet.Cells[row, 1].Text,              // A列
                LocationId = worksheet.Cells[row, 2].Text,        // B列
                ShortLocationId = worksheet.Cells[row, 4].Text,   // D列
                NmHallId = worksheet.Cells[row, 43].Text,         // AP列
                NmAisle = worksheet.Cells[row, 46].Text           // AS列
            };
            locations.Add(location);

            // 每1000条数据批量保存
            if (locations.Count >= 1000)
            {
                _context.Locations.AddRange(locations);
                await _context.SaveChangesAsync();
                locations.Clear();
            }
        }

        // 保存剩余数据
        if (locations.Any())
        {
            _context.Locations.AddRange(locations);
            await _context.SaveChangesAsync();
        }

        return Ok(new { Message = "File uploaded successfully.", RowsProcessed = worksheet.Dimension.End.Row - 1 });
    }
    catch (Exception ex)
    {
        return BadRequest($"Error processing file: {ex.Message}");
    }
}

已尝试的解决步骤 #

• 简化端点逻辑为仅验证文件存在，确认参数为[FromForm] IFormFile file，Postman仍返回"file字段必填"错误
• 注释上传控制器后Swagger可正常加载，确认[FromForm]与IFormFile结合导致Swagger崩溃
• 检查Postman，确认Content-Type自动设为multipart/form-data，未手动添加请求头

解决方案 #

1. 修复Swagger加载问题 #

ASP.NET Core 8中，Swashbuckle需要显式配置IFormFile的Schema映射。在Program.cs的Swagger配置中添加以下代码：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi", Version = "v1" });

    // 配置IFormFile的Swagger Schema支持
    c.MapType<IFormFile>(() => new OpenApiSchema
    {
        Type = "string",
        Format = "binary"
    });
});

同时确保Swashbuckle.AspNetCore包版本兼容ASP.NET Core 8，建议升级到6.4.0及以上的稳定版本。

2. 修复Postman"file字段必填"问题 #

• 参数名严格匹配：Postman中form-data的Key名称必须是file，与控制器参数名完全一致（大小写敏感）
• 正确选择类型：在Postman的Body标签下，选择form-data后，将Key的类型切换为File，再选择要上传的Excel文件
• 禁止手动设置Content-Type：让Postman自动生成multipart/form-data请求头，手动设置会丢失boundary分隔符信息
• 完善参数校验：在控制器方法开头添加空值检查，避免UploadHandler.ValidateFile提前抛出混淆错误：

  if (file == null || file.Length == 0)
      return BadRequest("No file uploaded.");
  

3. 补充全局请求大小限制 #

除了控制器上的[RequestSizeLimit]特性，建议在Program.cs中配置全局表单请求限制，避免局部配置失效：

builder.Services.Configure<FormOptions>(options =>
{
    options.MultipartBodyLengthLimit = 104857600; // 100MB
});

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