快捷導(dǎo)航

Asp.Net Core WebAPI使用Swagger時(shí)API隱藏和分組詳解

更新時(shí)間：2019年04月04日 10:23:38 作者：進(jìn)擊的辣條

這篇文章主要給大家介紹了關(guān)于Asp.Net Core WebAPI使用Swagger時(shí)API隱藏和分組的相關(guān)資料，文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家學(xué)習(xí)或者使用Asp.Net Core具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面來(lái)一起學(xué)習(xí)學(xué)習(xí)吧

1、前言

為什么我們要隱藏部分接口？

因?yàn)槲覀冊(cè)谟胹wagger代替接口的時(shí)候，難免有些接口會(huì)直觀的暴露出來(lái)，比如我們結(jié)合Consul一起使用的時(shí)候，會(huì)將健康檢查接口以及報(bào)警通知接口暴露出來(lái)，這些接口有時(shí)候會(huì)出于方便考慮，沒(méi)有進(jìn)行加密，這個(gè)時(shí)候我們就需要把接口隱藏起來(lái)，只有內(nèi)部的開(kāi)發(fā)者知道。

為什么要分組？

通常當(dāng)我們寫(xiě)前后端分離的項(xiàng)目的時(shí)候，難免會(huì)遇到編寫(xiě)很多接口供前端頁(yè)面進(jìn)行調(diào)用，當(dāng)接口達(dá)到幾百個(gè)的時(shí)候就需要區(qū)分哪些是框架接口，哪些是業(yè)務(wù)接口，這時(shí)候給swaggerUI的接口分組是個(gè)不錯(cuò)的選擇。

swagger的基本使用這里將不再贅述，可以閱讀微軟官方文檔，即可基本使用

2、swaggerUI中加入授權(quán)請(qǐng)求

新建HttpHeaderOperationFilter操作過(guò)濾器，繼承Swashbuckle.AspNetCore.SwaggerGen.IOperationFilter接口，實(shí)現(xiàn)Apply方法

/// <summary>
/// swagger請(qǐng)求頭
/// </summary>
public class HttpHeaderOperationFilter : IOperationFilter
{
 public void Apply(Operation operation, OperationFilterContext context)
 {
  #region 新方法
  if (operation.Parameters == null)
  {
   operation.Parameters = new List<IParameter>();
  }

  if (context.ApiDescription.TryGetMethodInfo(out MethodInfo methodInfo))
  {
   if (!methodInfo.CustomAttributes.Any(t => t.AttributeType == typeof(AllowAnonymousAttribute))
     &&!(methodInfo.ReflectedType.CustomAttributes.Any(t => t.AttributeType == typeof(AuthorizeAttribute))))
   {
    operation.Parameters.Add(new NonBodyParameter
    {
     Name = "Authorization",
     In = "header",
     Type = "string",
     Required = true,
     Description = "請(qǐng)輸入Token，格式為bearer XXX"
    });
   }
  }
  #endregion

  #region 已過(guò)時(shí)
  //if (operation.Parameters == null)
  //{
  // operation.Parameters = new List<IParameter>();
  //}
  //var actionAttrs = context.ApiDescription.ActionAttributes().ToList();
  //var isAuthorized = actionAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));
  //if (isAuthorized == false)
  //{
  // var controllerAttrs = context.ApiDescription.ControllerAttributes();
  // isAuthorized = controllerAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));
  //}
  //var isAllowAnonymous = actionAttrs.Any(a => a.GetType() == typeof(AllowAnonymousAttribute));
  //if (isAuthorized && isAllowAnonymous == false)
  //{
  // operation.Parameters.Add(new NonBodyParameter
  // {
  //  Name = "Authorization",
  //  In = "header",
  //  Type = "string",
  //  Required = true,
  //  Description = "請(qǐng)輸入Token，格式為bearer XXX"
  // });
  //}
  #endregion
 }
}

然后修改Startup.cs中的ConfigureServices方法，添加我們自定義的HttpHeaderOperationFilter過(guò)濾器

public IServiceProvider ConfigureServices(IServiceCollection services)
{
 ...
 services.AddSwaggerGen(c =>
 {
  ...
  c.OperationFilter<HttpHeaderOperationFilter>();
 });
 ...
}

這時(shí)候我們?cè)僭L問(wèn)swaggerUI就可以輸入Token了

3、API分組

修改Startup.cs中的ConfigureServices方法，添加多個(gè)swagger文檔

public IServiceProvider ConfigureServices(IServiceCollection services)
{
 ...
 services.AddSwaggerGen(c =>
 {
  c.SwaggerDoc("v1", new Info
  {
   Version = "v1",
   Title = "接口文檔",
   Description = "接口文檔-基礎(chǔ)",
   TermsOfService = "",
   Contact = new Contact
   {
    Name = "XXX1111",
    Email = "XXX1111@qq.com",
    Url = ""
   }
  });

  c.SwaggerDoc("v2", new Info
  {
   Version = "v2",
   Title = "接口文檔",
   Description = "接口文檔-基礎(chǔ)",
   TermsOfService = "",
   Contact = new Contact
   {
    Name = "XXX2222",
    Email = "XXX2222@qq.com",
    Url = ""
   }
  });

  //反射注入全部程序集說(shuō)明
  GetAllAssemblies().Where(t => t.CodeBase.EndsWith("Controller.dll")).ToList().ForEach(assembly =>
   {
    c.IncludeXmlComments(assembly.CodeBase.Replace(".dll", ".xml"));
   });

  c.OperationFilter<HttpHeaderOperationFilter>();
  //c.DocumentFilter<HiddenApiFilter>();
 });
 ...
}

修改Startup.cs中的Configure方法，加入

public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
 ...
 app.UseSwagger();
 app.UseSwaggerUI(c =>
 {
  c.SwaggerEndpoint("/swagger/v2/swagger.json", "接口文檔-基礎(chǔ)");//業(yè)務(wù)接口文檔首先顯示
  c.SwaggerEndpoint("/swagger/v1/swagger.json", "接口文檔-業(yè)務(wù)");//基礎(chǔ)接口文檔放后面后顯示
  c.RoutePrefix = string.Empty;//設(shè)置后直接輸入IP就可以進(jìn)入接口文檔
 });
 ...

}

然后還要在我們的控制器上面標(biāo)注swagger文檔的版本

這時(shí)候我們就可以將接口文檔進(jìn)行分組顯示了

4、API隱藏

創(chuàng)建自定義隱藏特性HiddenApiAttribute.cs

/// <summary>
/// 隱藏swagger接口特性標(biāo)識(shí)
/// </summary>
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class HiddenApiAttribute:System.Attribute
{
}

創(chuàng)建API隱藏過(guò)濾器HiddenApiFilter繼承Swashbuckle.AspNetCore.SwaggerGen.IDocumentFilter接口，實(shí)現(xiàn)Apply方法

/// <summary>
/// 自定義Swagger隱藏過(guò)濾器
/// </summary>
public class HiddenApiFilter : IDocumentFilter
{
 public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
 {
  foreach (ApiDescription apiDescription in context.ApiDescriptions)
  {
   if (apiDescription.TryGetMethodInfo(out MethodInfo method))
   {
    if (method.ReflectedType.CustomAttributes.Any(t=>t.AttributeType==typeof(HiddenApiAttribute))
      || method.CustomAttributes.Any(t => t.AttributeType == typeof(HiddenApiAttribute)))
    {
     string key = "/" + apiDescription.RelativePath;
     if (key.Contains("?"))
     {
      int idx = key.IndexOf("?", System.StringComparison.Ordinal);
      key = key.Substring(0, idx);
     }
     swaggerDoc.Paths.Remove(key);
    }
   }
  }
 }
}

在Startup.cs中使用HiddenApiFilter

public IServiceProvider ConfigureServices(IServiceCollection services)
{
 ...
 services.AddSwaggerGen(c =>
 {
  c.SwaggerDoc("v1", new Info
  {
   Version = "v1",
   Title = "接口文檔",
   Description = "接口文檔-基礎(chǔ)",
   TermsOfService = "",
   Contact = new Contact
   {
    Name = "XXX1111",
    Email = "XXX1111@qq.com",
    Url = ""
   }
  });

  c.SwaggerDoc("v2", new Info
  {
   Version = "v2",
   Title = "接口文檔",
   Description = "接口文檔-基礎(chǔ)",
   TermsOfService = "",
   Contact = new Contact
   {
    Name = "XXX2222",
    Email = "XXX2222@qq.com",
    Url = ""
   }
  });

  //反射注入全部程序集說(shuō)明
  GetAllAssemblies().Where(t => t.CodeBase.EndsWith("Controller.dll")
   && !t.CodeBase.Contains("Common.Controller.dll")).ToList().ForEach(assembly =>
   {
    c.IncludeXmlComments(assembly.CodeBase.Replace(".dll", ".xml"));
   });

  c.OperationFilter<HttpHeaderOperationFilter>();
  c.DocumentFilter<HiddenApiFilter>();
 });
 ...
}

示例：

我這里提供了Consul的心跳檢車(chē)接口