如何为直接读取Request.Body的ASP.NET Core Action生成Swagger文档

当然可以搞定这个问题！因为你禁用了模型绑定，Swagger没办法自动识别接口的请求结构，所以我们需要手动给Swagger补充必要的元数据，让它知道这是一个支持文件上传的接口。下面给你两种实用的方案：

方案一：添加虚拟文件参数（简单快速） #

虽然你在代码里直接读取Request.Body，但可以在Action方法上添加一个虚拟的IFormFile参数，并用[FromForm]标记，这个参数你完全不需要在业务逻辑里使用，只是用来给Swagger生成文档用的：

[HttpPost("upload")]
[DisableFormValueModelBinding]
[Consumes("multipart/form-data")] // 明确指定接口接收的内容类型
public async Task<IActionResult> UploadAsync([FromForm] IFormFile file) 
{
    // 依然按你的需求直接读取Request.Body，不用管file参数
    using var stream = Request.Body;
    // 你的文件处理逻辑...
    return Ok();
}

添加后Swagger UI会自动生成文件上传控件，同时因为你用了[DisableFormValueModelBinding]，ASP.NET Core不会对这个虚拟参数做模型绑定，完全不影响你手动读取请求体的逻辑。

方案二：自定义Swagger操作过滤器（更灵活） #

如果你不想添加虚拟参数，可以通过自定义操作过滤器，在Swagger生成文档时手动注入文件上传的请求结构：

1. 先创建操作过滤器类：

public class FileUploadOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 匹配你的上传接口（这里按路由和请求方法判断，也可以用自定义特性标记）
        var isUploadAction = context.ApiDescription.HttpMethod == HttpMethod.Post.Method &&
                             context.ApiDescription.RelativePath.Equals("upload", StringComparison.OrdinalIgnoreCase);

        if (isUploadAction)
        {
            // 构造multipart/form-data类型的请求体定义
            operation.RequestBody = new OpenApiRequestBody
            {
                Content = new Dictionary<string, OpenApiMediaType>
                {
                    ["multipart/form-data"] = new OpenApiMediaType
                    {
                        Schema = new OpenApiSchema
                        {
                            Type = "object",
                            Properties = new Dictionary<string, OpenApiSchema>
                            {
                                ["file"] = new OpenApiSchema
                                {
                                    Type = "string",
                                    Format = "binary" // 标记为二进制文件类型
                                }
                            },
                            Required = new HashSet<string> { "file" } // 可选：标记文件为必填项
                        }
                    }
                }
            };
        }
    }
}

2. 在Program.cs/Startup.cs中注册这个过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<FileUploadOperationFilter>();
});

这种方式更灵活，你可以根据路由、自定义特性等条件精准控制哪些接口需要生成文件上传契约，完全不需要修改Action的参数列表。

额外提示 #

• 记得给Action加上[Consumes("multipart/form-data")]，明确告诉Swagger和ASP.NET Core接口接收的内容类型，避免混淆。
• 如果需要支持多文件上传，方案一中只需把参数改成List<IFormFile>，方案二中则在Properties里添加多个文件字段即可。

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