Asp.Net Core WebAPI使用Swagger時API隱藏與分組
阿新 • • 發佈：2019-05-10
sum pro build 程序集 cto fse 區分 分組 odi 原文:Asp.Net Core WebAPI使用Swagger時API隱藏與分組
1、前言
為什麽我們要隱藏部分接口？
因為我們在用swagger代替接口的時候，難免有些接口會直觀的暴露出來，比如我們結合Consul一起使用的時候，會將健康檢查接口以及報警通知接口暴露出來，這些接口有時候會出於方便考慮，沒有進行加密，這個時候我們就需要把接口隱藏起來，只有內部的開發者知道。
為什麽要分組？
通常當我們寫前後端分離的項目的時候，難免會遇到編寫很多接口供前端頁面進行調用，當接口達到幾百個的時候就需要區分哪些是框架接口，哪些是業務接口，這時候給swaggerUI的接口分組是個不錯的選擇。
swagger的基本使用這裏將不再贅述，可以閱讀微軟官方文檔，即可基本使用
2、swaggerUI中加入授權請求
- 新建 HttpHeaderOperationFilter 操作過濾器，繼承 Swashbuckle.AspNetCore.SwaggerGen.IOperationFilter 接口，實現 Apply 方法
/// <summary> /// swagger請求頭 /// </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 = "請輸入Token，格式為bearer XXX" }); } } #endregion #region 已過時 //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 = "請輸入Token，格式為bearer XXX" // }); //} #endregion } } - 然後修改 Startup.cs 中的 ConfigureServices 方法，添加我們自定義的 HttpHeaderOperationFilter 過濾器
public IServiceProvider ConfigureServices(IServiceCollection services) { ... services.AddSwaggerGen(c => { ... c.OperationFilter<HttpHeaderOperationFilter>(); }); ... }
這時候我們再訪問swaggerUI就可以輸入Token了
3、API分組
- 修改 Startup.cs 中的 ConfigureServices 方法，添加多個swagger文檔
public IServiceProvider ConfigureServices(IServiceCollection services) { ... services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new Info { Version = "v1", Title = "接口文檔", Description = "接口文檔-基礎", TermsOfService = "", Contact = new Contact { Name = "XXX1111", Email = "[email protected]", Url = "" } }); c.SwaggerDoc("v2", new Info { Version = "v2", Title = "接口文檔", Description = "接口文檔-基礎", TermsOfService = "", Contact = new Contact { Name = "XXX2222", Email = "[email protected]", Url = "" } }); //反射註入全部程序集說明 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", "接口文檔-基礎");//業務接口文檔首先顯示 c.SwaggerEndpoint("/swagger/v1/swagger.json", "接口文檔-業務");//基礎接口文檔放後面後顯示 c.RoutePrefix = string.Empty;//設置後直接輸入IP就可以進入接口文檔 }); ... }
-
然後還要在我們的控制器上面標註swagger文檔的版本
這時候我們就可以將接口文檔進行分組顯示了
4、API隱藏
- 創建自定義隱藏特性 HiddenApiAttribute.cs
/// <summary> /// 隱藏swagger接口特性標識 /// </summary> [AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)] public class HiddenApiAttribute:System.Attribute { }
- 創建API隱藏過濾器 HiddenApiFilter 繼承 Swashbuckle.AspNetCore.SwaggerGen.IDocumentFilter 接口，實現 Apply 方法
/// <summary> /// 自定義Swagger隱藏過濾器 /// </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 = "接口文檔-基礎", TermsOfService = "", Contact = new Contact { Name = "XXX1111", Email = "[email protected]", Url = "" } }); c.SwaggerDoc("v2", new Info { Version = "v2", Title = "接口文檔", Description = "接口文檔-基礎", TermsOfService = "", Contact = new Contact { Name = "XXX2222", Email = "[email protected]", Url = "" } }); //反射註入全部程序集說明 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的心跳檢車接口
但是在接口文檔中並沒有顯示出來
Asp.Net Core WebAPI使用Swagger時API隱藏與分組