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 = "XXX1111@qq.com", Url = "" } }); c.SwaggerDoc("v2", new Info { Version = "v2", Title = "接口文档", Description = "接口文档-基础", TermsOfService = "", Contact = new Contact { Name = "XXX2222", Email = "XXX2222@qq.com", 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 = "XXX1111@qq.com", Url = "" } }); c.SwaggerDoc("v2", new Info { Version = "v2", Title = "接口文档", Description = "接口文档-基础", TermsOfService = "", Contact = new Contact { Name = "XXX2222", Email = "XXX2222@qq.com", 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的心跳检车接口
但是在接口文档中并没有显示出来
总结
以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,谢谢大家对猪先飞的支持。
相关文章
- 这篇文章主要介绍了.NET Core下使用Kafka的方法步骤,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2021-09-22
- 这篇文章主要介绍了Swagger中@ApiIgnore注解的使用,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教...2021-10-21
- 这篇文章主要介绍了详解.NET Core 3.0 里新的JSON API,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2021-09-22
ASP.NET Core根据环境变量支持多个 appsettings.json配置文件
这篇文章主要介绍了ASP.NET Core根据环境变量支持多个 appsettings.json配置文件,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2021-09-22- 这篇文章主要介绍了记一次EFCore类型转换错误及解决方案,帮助大家更好的理解和学习使用asp.net core,感兴趣的朋友可以了解下...2021-09-22
详解ASP.NET Core 中基于工厂的中间件激活的实现方法
这篇文章主要介绍了ASP.NET Core 中基于工厂的中间件激活的实现方法,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下...2021-09-22- Underscore 是一个 JavaScript 工具库,它提供了一整套函数式编程的实用功能,但是没有扩展任何 JavaScript 内置对象。这篇文章主要介绍了underscore源码分析相关知识,感兴趣的朋友一起学习吧...2016-01-02
详解.NET Core 使用HttpClient SSL请求出错的解决办法
这篇文章主要介绍了.NET Core 使用HttpClient SSL请求出错的解决办法,小编觉得挺不错的,现在分享给大家,也给大家做个参考。一起跟随小编过来看看吧...2021-09-22- 这篇文章主要介绍了c# webapi 配置swagger的方法,文中示例代码非常详细,帮助大家更好的理解和学习,感兴趣的朋友可以了解下...2020-07-09
- 这篇文章主要介绍了C# WebApi 接口传参详解,本篇打算通过get、post、put、delete四种请求方式分别谈谈基础类型(包括int/string/datetime等)、实体、数组等类型的参数如何传递。感兴趣的小伙伴们可以参考一下...2020-06-25
.net EF Core专题:EF Core 读取数据时发生了什么?
这篇文章主要介绍了EF Core 读取数据的的相关知识,文中讲解非常细致,代码帮助大家更好的理解和学习,感兴趣的朋友可以了解下...2021-09-22- 这篇文章主要介绍了详解ASP.NET Core Token认证,小编觉得挺不错的,现在分享给大家,也给大家做个参考。...2021-09-22
- 这篇文章主要介绍了Swagger2匹配多个controller代码实例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下...2020-09-19
- .net core是最近讨论频率很高的话题,下面这篇文章主要给大家介绍了关于利用.NET Core如何获取操作系统中各种信息的相关资料,文中通过示例代码介绍的非常详细,需要的朋友可以参考借鉴,下面来一起看看吧...2021-09-22
- 这篇文章主要介绍了asp.net core MVC之实现基于token的认证,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2021-05-07
- 这篇文章主要介绍了ASP.NET Core如何注入多个服务实现类的相关资料,需要的朋友可以参考下面文章的具体内容...2021-09-22
- 这篇文章主要介绍了ASP.NET Core使用JWT认证授权的方法,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2021-09-22
ASP.NET core Web中使用appsettings.json配置文件的方法
这篇文章主要给大家介绍了在ASP.NET core Web中使用appsettings.json配置文件的方法,文中给出了详细的示例代码,需要的朋友可以参考学习,下面来一起看看吧。...2021-09-22- 这篇文章主要介绍了详解EFCore中的导航属性的相关资料,帮助大家更好的理解和学习使用ASP.NET CORE,感兴趣的朋友可以了解下...2021-09-22
ASP.NET Core MVC如何实现运行时动态定义Controller类型
这篇文章主要介绍了ASP.NET Core MVC如何实现运行时动态定义Controller类型,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧...2021-09-22