.Net Core小技巧 - 使用Swagger上傳文件

前言

 　　隨着先後端分離開發模式的普及，後端人員更可能是編寫服務端API接口。調用接口實現文件上傳是一個常見的功能，同時也須要一個選擇文件上傳的界面，能夠編寫前端界面上傳，能夠使用Postman、curl來模擬上傳請求。上述的方式多多少少有點麻煩。Swagger做爲Api說明文檔及調試工具，若是它能提供文件上傳的界面（默認不提供），那會更加方便文件上傳提示，本文將介紹如何使用Swagger來上傳文件。

 

步驟

1. 安裝Swagger

Install-Package Swashbuckle.AspNetCore

 

2. 配置Swagger中間件

在Startup.ConfigureServices中添加：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

 

在Startup.Configure中添加：

app.UseSwagger();

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

 

3. 編寫API

// POST api/values
[HttpPost]
public void Post(IFormFile file)
{
    //TODO:Save file...
}

// PUT api/values/5
[HttpPut("{id}")]
public void Put(int id, IFormFile file)
{
    //TODO:Save file...
}

 

4. 編寫SwaggerFileUploadFilter

public class SwaggerFileUploadFilter : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        if (!context.ApiDescription.HttpMethod.Equals("POST", StringComparison.OrdinalIgnoreCase) &&
            !context.ApiDescription.HttpMethod.Equals("PUT", StringComparison.OrdinalIgnoreCase))
        {
            return;
        }

        var fileParameters = context.ApiDescription.ActionDescriptor.Parameters.Where(n => n.ParameterType == typeof(IFormFile)).ToList();

        if (fileParameters.Count < 0)
        {
            return;
        }

        operation.Consumes.Add("multipart/form-data");

        foreach (var fileParameter in fileParameters)
        {
            var parameter = operation.Parameters.Single(n => n.Name == fileParameter.Name);
            operation.Parameters.Remove(parameter);
            operation.Parameters.Add(new NonBodyParameter
            {
                Name = parameter.Name,
                In = "formData",
                Description = parameter.Description,
                Required = parameter.Required,
                Type = "file"
            });
        }
    }
}

 

5. 註冊SwaggerFileUploadFilter

c.OperationFilter<SwaggerFileUploadFilter>();

 

6. 查看結果

POST方法：

 

PUT方法：

 

原理解析

　　使用Swagger的文件上傳的關鍵在於SwaggerFileUploadFilter，它繼承於Swashbuckle的IOperationFilter，也即它只做用於Swagger，不會對其它模塊形成影響。

　　咱們再來看一下SwaggerFileUploadFilter裏面的Apply方法的邏輯：

　　1. 判斷請求的方法是否爲POST或者PUT，若是是其它請求方法，基本不多是文件上傳操做。

　　2. 查找方法中類型爲IFormFile的參數。

　　3. 設置Consumes爲「multipart/form-data」。

　　4. 替換IFormFile類型參數描述中的In爲formData、Type爲File。

 

源碼地址

https://github.com/ErikXu/.NetCoreTips/tree/master/SwaggerFileUpload

 

參考資料

http://www.talkingdotnet.com/how-to-upload-file-via-swagger-in-asp-net-core-web-api/