使用Swagger直接上傳文件的方法

常常使用swagger，能夠經過設置[ProducesResponseType]標記接口的返回信息；swagger也能經過接口的參數列表，自動得到發送的數據結構信息。

不過有一個例外，就是上傳文件的時候，設置了[Consumes]的內容爲multi-part/form-data，可是swagger並不能正常感知是上傳文件的。代碼是這個樣子的：

關於文件上傳的細節，能夠看多年前我寫過一篇有關經過WEBAPI上傳文件的文章。

[Consumes("multipart/form-data")]
[ODataRoute]
[HttpPost]
public async Task<ActionResult> Post(IFormCollection collection)
{
    var file = collection.Files[0];
    if(file != null)
    {
        var filename = DateTime.Now.ToString("yyyyMMddHHmmss") + file.FileName;
        var path = Path.Combine(_webHostEnvironment.WebRootPath, "Files", filename);
        using FileStream fileStream = new FileStream(path, FileMode.Create);
        await file.CopyToAsync(fileStream);
        var uri = "Files/" + filename;
        var fileEntity = new Models.File { Url = uri, LastModified = DateTime.Now };
        _homeworkDataContext.Files.Add(fileEntity);
        await _homeworkDataContext.SaveChangesAsync();
        return Created(WebUtility.UrlEncode(uri), fileEntity);
    }
    return BadRequest();
}

實際上，swagger一直提示，上傳的內容是一個array類型，固然API是沒有問題的，能夠經過POSTMAN進行發送，不過不能在網頁上直接操做，總以爲內心有點不太舒服。

方法

搜索了一下辦法，比較靠譜的，就是經過增長一個IOperationFilter來實現目的。

// CODE FROM https://www.talkingdotnet.com/how-to-upload-file-via-swagger-in-asp-net-core-web-api/
public class FileUploadOperation : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        if (operation.OperationId.ToLower() == "apivaluesuploadpost")
        {
            operation.Parameters.Clear();
            operation.Parameters.Add(new NonBodyParameter
            {
                Name = "uploadedFile",
                In = "formData",
                Description = "Upload File",
                Required = true,
                Type = "file"
            });
            operation.Consumes.Add("multipart/form-data");
        }
    }
}

而後，在services.ConfigureSwaggerGen()參數中，添加

options.OperationFilter<FileUploadOperation>();

方法的原理是經過重寫操做某個特定API的的過濾器，來實現對返回內容的操做。

此方法適用於OAS2，實質上是實現了這裏的規範要求。

我已經用上.NET 5.0了，自帶了swagger都支持的是OpenAPI 3，這個方法很差用了。不過思想應該相同，首先看看OpenAPI 3的規範，文件上傳須要定義爲：

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          fileName:
            type: string
            format: binary

這個套路和OpenAPI 2徹底不同，須要從新設置requestBody才行。咱們按照要求改造代碼。

public class FileUploadOperation : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        //判斷上傳文件的類型，只有上傳的類型是IFormCollection的才進行重寫。
        if (context.ApiDescription.ActionDescriptor.Parameters.Any(w => w.ParameterType == typeof(IFormCollection)))
        {
            Dictionary<string, OpenApiSchema> schema = new Dictionary<string, OpenApiSchema>();
            schema["fileName"] = new OpenApiSchema { Description = "Select file", Type = "string", Format = "binary" };
            Dictionary<string, OpenApiMediaType> content = new Dictionary<string, OpenApiMediaType>();
            content["multipart/form-data"] = new OpenApiMediaType { Schema = new OpenApiSchema { Type = "object", Properties = schema } };
            operation.RequestBody = new OpenApiRequestBody() { Content = content };
        }
    }
}

執行以後，swagger已經能夠正常識別了，經過選擇文件便可上傳，效果以下：

參考資料

• https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-5.0&tabs=visual-studio
• https://docs.microsoft.com/en-us/aspnet/core/mvc/models/file-uploads?view=aspnetcore-5.0#upload-large-files-with-streaming
• https://www.talkingdotnet.com/how-to-upload-file-via-swagger-in-asp-net-core-web-api/