快捷導(dǎo)航

swagger上傳文件并支持jwt認(rèn)證的實(shí)現(xiàn)方法

更新時間：2018年05月14日 16:05:50 作者：Chaunce

今天通過本文給大家分享swagger上傳文件并支持jwt認(rèn)證的實(shí)現(xiàn)方法，文中提到了安裝方法及實(shí)現(xiàn)代碼，感興趣的朋友跟隨腳本之家小編一起學(xué)習(xí)吧

什么是 Swagger?

Swagger的目標(biāo)是為REST APIs 定義一個標(biāo)準(zhǔn)的，與語言無關(guān)的接口，使人和計(jì)算機(jī)在看不到源碼或者看不到文檔或者不能通過網(wǎng)絡(luò)流量檢測的情況下能發(fā)現(xiàn)和理解各種服務(wù)的功能。當(dāng)服務(wù)通過Swagger定義，消費(fèi)者就能與遠(yuǎn)程的服務(wù)互動通過少量的實(shí)現(xiàn)邏輯。類似于低級編程接口，Swagger去掉了調(diào)用服務(wù)時的很多猜測。

背景

　　由于swagger不僅提供了自動實(shí)現(xiàn)接口文檔的說明而且支持頁面調(diào)試，告別postman等工具，無需開發(fā)人員手動寫api文檔，縮減開發(fā)成本得到大家廣泛認(rèn)可但是由于swagger沒有提供上傳文件的支持，所以只能靠開發(fā)人員自己實(shí)現(xiàn)。今天就來看看如何擴(kuò)展swagger達(dá)到上傳文件的需求

動起小手手

1安裝swagger

nuget安裝Swashbuckle.AspNetCore.Swagger組件

2設(shè)置生成xml

右鍵項(xiàng)目>屬性>生成

相應(yīng)的把其他需要生成文檔說明的項(xiàng)目也按上步驟進(jìn)行設(shè)置xml

關(guān)鍵swagger代碼

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.PlatformAbstractions;
using Swashbuckle.AspNetCore.Swagger;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
namespace Chaunce.Api.App_Start
{
 /// <summary>
 /// SwaggerConfig
 /// </summary>
 public class SwaggerConfig
 {
  /// <summary>
  /// InitSwagger
  /// </summary>
  /// <param name="services"></param>
  public static void InitSwagger(IServiceCollection services)
  {
   services.AddSwaggerGen(c =>
   {
    c.OperationFilter<SwaggerFileUploadFilter>();//增加文件過濾處理
    var security = new Dictionary<string, IEnumerable<string>> { { "Bearer", new string[] { } }, };
    c.AddSecurityRequirement(security);//添加一個必須的全局安全信息，和AddSecurityDefinition方法指定的方案名稱要一致，這里是Bearer。
    var basePath = PlatformServices.Default.Application.ApplicationBasePath;// 獲取到應(yīng)用程序的根路徑
    var xmlApiPath = Path.Combine(basePath, "Chaunce.Api.xml");//api文件xml(在以上步驟2設(shè)置生成xml的路徑)
    var xmlModelPath = Path.Combine(basePath, "Chaunce.ViewModels.xml");//請求modelxml
    c.IncludeXmlComments(xmlApiPath);
    c.IncludeXmlComments(xmlModelPath);
    c.SwaggerDoc("v1", new Info
    {
     Title = "Chaunce數(shù)據(jù)接口",
     Version = "v1",
     Description = "這是一個webapi接口文檔說明",
     TermsOfService = "None",
     Contact = new Contact { Name = "Chaunce官網(wǎng)", Email = "info@Chaunce.com", Url = "http://blog.Chaunce.top/" },
     License = new License
     {
      Name = "Swagger官網(wǎng)",
      Url = "http://swagger.io/",
     }
    });
    c.IgnoreObsoleteActions();
    c.AddSecurityDefinition("Bearer", new ApiKeyScheme
    {
     Description = "權(quán)限認(rèn)證(數(shù)據(jù)將在請求頭中進(jìn)行傳輸) 參數(shù)結(jié)構(gòu): \"Authorization: Bearer {token}\"",
     Name = "Authorization",//jwt默認(rèn)的參數(shù)名稱
     In = "header",//jwt默認(rèn)存放Authorization信息的位置(請求頭中)
     Type = "apiKey"
    });//Authorization的設(shè)置
   });
  }
  /// <summary>
  /// ConfigureSwagger
  /// </summary>
  /// <param name="app"></param>
  public static void ConfigureSwagger(IApplicationBuilder app)
  {
   app.UseSwagger();
   // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
   app.UseSwagger(c =>
   {
    c.RouteTemplate = "docs/{documentName}/docs.json";//使中間件服務(wù)生成Swagger作為JSON端點(diǎn)(此處設(shè)置是生成接口文檔信息，可以理解為老技術(shù)中的webservice的soap協(xié)議的信息，暴露出接口信息的地方)
    c.PreSerializeFilters.Add((swaggerDoc, httpReq) => swaggerDoc.Info.Description = httpReq.Path);//請求過濾處理
   });
   app.UseSwaggerUI(c =>
   {
    c.RoutePrefix = "docs";//設(shè)置文檔首頁根路徑
    c.SwaggerEndpoint("/docs/v1/docs.json", "V1");//此處配置要和UseSwagger的RouteTemplate匹配
    //c.SwaggerEndpoint("/swagger/v1/swagger.json", "V1");//默認(rèn)終結(jié)點(diǎn)
    c.InjectStylesheet("/swagger-ui/custom.css");//注入style文件
   });
  }
 }
}

swagger過濾器

using Microsoft.AspNetCore.Http;
using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
namespace Chaunce.Api.Help
{
 /// <summary>
 /// swagger文件過濾器
 /// </summary>
 public class SwaggerFileUploadFilter : IOperationFilter
 {
  /// <summary>
  /// swagger過濾器（此處的Apply會被swagger的每個接口都調(diào)用生成文檔說明，所以在此處可以對每一個接口進(jìn)行過濾操作）
  /// </summary>
  /// <param name="operation"></param>
  /// <param name="context"></param>
  public void Apply(Operation operation, OperationFilterContext context)
  {
   if (!context.ApiDescription.HttpMethod.Equals("POST", StringComparison.OrdinalIgnoreCase) &&
   !context.ApiDescription.HttpMethod.Equals("PUT", StringComparison.OrdinalIgnoreCase))
   {
    return;
   }
   var apiDescription = context.ApiDescription;
   var parameters = context.ApiDescription.ParameterDescriptions.Where(n => n.Type == typeof(IFormFileCollection) || n.Type == typeof(IFormFile)).ToList();//parameterDescriptions包含了每個接口所帶所有參數(shù)信息
   if (parameters.Count() <= 0)
   {
    return;
   }
   operation.Consumes.Add("multipart/form-data");
   foreach (var fileParameter in parameters)
   {
    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",
     //CollectionFormat = "multi"
    });
   }
  }
 }
}