ASP.NET Core 6 Web API如何配置Swagger生成file类型参数

默认情况下ASP.NET Core 6集成的Swashbuckle组件生成的是OpenAPI 3.0规范文档，文件上传参数会被封装为requestBody下的object结构，文件属性标记为type: string, format: binary。你提到的type: file格式是Swagger 2.0（OpenAPI 2.0）的文件参数声明规则，旧版本swagger-codegen默认按2.0规范解析，就无法正确识别默认生成的3.0结构。

你可以根据实际场景二选一：

方案1：修改Swagger配置生成符合Swagger 2.0规范的文件参数结构 #

如果需要保留当前使用的swagger-codegen版本，直接在项目中添加自定义操作过滤器，同时指定Swagger输出2.0规范即可，步骤如下：

• 在项目中新增如下操作过滤器代码：

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

public class FormFileParamsFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 查找接口中标记[FromForm]的IFormFile类型参数
        var fileParams = context.MethodInfo.GetParameters()
            .Where(p => p.ParameterType == typeof(IFormFile) 
                && p.GetCustomAttributes(typeof(FromFormAttribute), true).Any())
            .ToList();
        
        if (!fileParams.Any()) return;

        // 清除默认生成的object类型requestBody
        operation.RequestBody = null;
        operation.Parameters ??= new List<OpenApiParameter>();

        // 按Swagger 2.0规范添加formData类型的file参数
        foreach (var param in fileParams)
        {
            operation.Parameters.Add(new OpenApiParameter
            {
                Name = param.Name,
                In = ParameterLocation.FormData,
                Required = !param.IsOptional,
                Schema = new OpenApiSchema
                {
                    Type = "file"
                },
                Description = "待上传的文件"
            });
        }

        // 标记接口请求类型为multipart/form-data
        operation.Extensions["consumes"] = new Microsoft.OpenApi.Any.OpenApiArray
        {
            new Microsoft.OpenApi.Any.OpenApiString("multipart/form-data")
        };
    }
}

• 在Program.cs的Swagger服务配置中注册过滤器，同时开启2.0规范输出：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API服务名称", Version = "v1" });
    // 注册自定义文件参数过滤器
    c.OperationFilter<FormFileParamsFilter>();
    // 指定输出Swagger 2.0格式文档
    c.SerializeAsV2 = true;
});

配置完成后重启项目，Swagger文档中的文件参数就会生成你需要的type: file结构，swagger-codegen可以正常识别生成TypeScript客户端代码。
如果你的接口同时接收其他普通表单字段，只需要在过滤器中同步把非文件类型的FromForm参数也加入Parameters列表即可，不要保留默认的RequestBody结构避免参数重复识别。

方案2：升级swagger-codegen版本适配OpenAPI 3.0规范 #

如果不想修改后端Swagger配置，直接将swagger-codegen升级到3.0及以上版本即可，3.x版本已经完整支持OpenAPI 3.0规范，可以直接识别默认生成的type: string, format: binary文件声明，不需要强制要求type: file的2.0格式，生成的客户端代码同样可以正常处理文件上传逻辑。

内容的提问来源于stack exchange，提问作者THX-1138