ASP.NET WebAPI 2用NSwag时OpenApi3无文件上传按钮问题求助

问题原因 #

OpenAPI 3.0 与 Swagger 2.0 对文件上传的规范定义存在本质差异：

• Swagger 2.0 通过 consumes: multipart/form-data + type: file 标记文件参数
• OpenAPI 3.0 要求通过 requestBody 的 multipart/form-data 内容类型，配合 type: string + format: binary 定义文件字段

你参照的方案仅适配了 Swagger 2.0 的规范，未处理 OpenAPI 3.0 的结构要求，导致切换 SchemaType 后控件无法渲染。

可行解决步骤 #

1. 确保 API 方法参数定义合规

使用 IFormFile 或包含 IFormFile 的模型作为上传参数，示例：

// 单文件上传
[HttpPost("upload")]
public IHttpActionResult UploadSingleFile(IFormFile file)
{
    // 业务逻辑
    return Ok();
}

// 带额外参数的文件上传
public class UploadRequest
{
    public IFormFile File { get; set; }
    public string FileName { get; set; }
}

[HttpPost("upload-with-meta")]
public IHttpActionResult UploadFileWithMeta(UploadRequest request)
{
    // 业务逻辑
    return Ok();
}

2. 自定义 NSwag 操作处理器适配 OpenAPI 3.0

NSwag 13.19.0 对 OpenAPI 3.0 的文件上传自动生成支持不完善，需添加自定义处理器转换参数结构：

public class OpenApiFileUploadProcessor : IOperationProcessor
{
    public bool Process(OperationProcessorContext context)
    {
        // 筛选出所有文件类型的参数
        var fileParams = context.OperationDescription.Parameters
            .Where(p => p.Type == typeof(IFormFile) || p.Type.IsAssignableFrom(typeof(IFormFile)))
            .ToList();

        if (!fileParams.Any()) return true;

        // 构建 OpenAPI 3.0 要求的 requestBody 结构
        var requestBody = new OpenApiRequestBody
        {
            Content = new Dictionary<string, OpenApiMediaType>
            {
                ["multipart/form-data"] = new OpenApiMediaType
                {
                    Schema = new OpenApiSchema
                    {
                        Type = "object",
                        Properties = fileParams.ToDictionary(
                            p => p.Name,
                            p => new OpenApiSchema { Type = "string", Format = "binary" }
                        )
                    }
                }
            }
        };

        // 替换原参数为 requestBody，并移除旧参数
        context.OperationDescription.Operation.RequestBody = requestBody;
        foreach (var param in fileParams)
        {
            context.OperationDescription.Parameters.Remove(param);
        }

        return true;
    }
}

3. 配置 NSwag 启用自定义处理器

在 NSwag 文档生成配置中添加该处理器：

var settings = new SwaggerDocumentGeneratorSettings
{
    SchemaType = SchemaType.OpenApi3,
    // 其他基础配置（如标题、版本等）
};

// 添加自定义文件上传处理器
settings.OperationProcessors.Add(new OpenApiFileUploadProcessor());

// 生成文档
var document = SwaggerDocumentGenerator.GenerateDocument(settings, typeof(WebApiApplication).Assembly);

4. 尝试升级 NSwag 版本（可选）

NSwag 13.19.0 属于较旧版本，后续的 13.x 稳定版或 14.x 版本（需确认兼容 .NET 4.7.1）已修复部分 OpenAPI 3.0 文件上传的自动生成问题，升级后可能无需自定义处理器即可解决问题。

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