数码控科技猎奇Iphone动漫星座游戏电竞lolcosplay王者荣耀攻略allcnewsBLOGNEWSBLOGASKBLOGBLOGZSK全部技术问答问答技术问答it问答代码软件新闻开发博客电脑/网络手机/数码笔记本电脑互联网操作系统软件硬件编程开发360产品资源分享电脑知识文档中心IT全部全部分类全部分类技术牛文全部分类教程最新网页制作cms教程平面设计媒体动画操作系统网站运营网络安全服务器教程数据库工具网络安全软件教学vbscript正则表达式javascript批处理更多»编程更新教程更新游戏更新allitnewsJava新闻网络医疗信息化安全创业站长电商科技访谈域名会议专栏创业动态融资创投创业学院 / 产品经理创业公司人物访谈营销开发数据库服务器系统虚拟化云计算嵌入式移动开发作业作业1常见软件all电脑网络手机数码生活游戏体育运动明星影音休闲爱好文化艺术社会民生教育科学医疗健康金融管理情感社交地区其他电脑互联网软件硬件编程开发360相关产品手机平板其他电子产品摄影器材360硬件通讯智能设备购物时尚生活常识美容塑身服装服饰出行旅游交通汽车购房置业家居装修美食烹饪单机电脑游戏网页游戏电视游戏桌游棋牌游戏手机游戏小游戏掌机游戏客户端游戏集体游戏其他游戏体育赛事篮球足球其他运动球类运动赛车健身运动运动用品影视娱乐人物音乐动漫摄影摄像收藏宠物幽默搞笑起名花鸟鱼虫茶艺彩票星座占卜书画美术舞蹈小说图书器乐声乐小品相声戏剧戏曲手工艺品历史话题时事政治就业职场军事国防节日风俗法律法规宗教礼仪礼节自然灾害360维权社会人物升学入学人文社科外语资格考试公务员留学出国家庭教育学习方法语文物理生物工程学农业数学化学健康知识心理健康孕育早教内科外科妇产科儿科皮肤科五官科男科整形中医药品传染科其他疾病医院两性肿瘤科创业投资企业管理财务税务银行股票金融理财基金债券保险贸易商务文书国民经济爱情婚姻家庭烦恼北京上海重庆天津黑龙江吉林辽宁河北内蒙古山西陕西宁夏甘肃青海新疆西藏四川贵州云南河南湖北湖南山东江苏浙江安徽江西福建广东广西海南香港澳门台湾海外地区

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的心跳检车接口

但是在接口文档中并没有显示出来

总结

以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,谢谢大家对脚本之家的支持。

您可能感兴趣的文章:


  • 本文相关:
  • asp.net core webapi 使用swagger生成帮助页实例
  • .net core2.1 webapi新增swagger插件详解
  • asp.net core 2.0 webapi全局配置及日志实例
  • 浅谈asp.net core webapi几种版本控制对比
  • asp.net core 2.0 webapi集成signalr(实例讲解)
  • ado.net中的五个主要对象的详细介绍与应用
  • aspx不显示viewstate的实例
  • asp.net导出word实例
  • c#中的fileupload 选择后的预览效果具体实现
  • 分享visual studio原生开发的10个调试技巧(2)
  • asp.net笔记之 控件与母板的区别分析
  • c#后台调用前台javascript的五种方法小结
  • asp.net中serverpush用法实例分析
  • 解析asp.net的分页控件
  • asp.net 身份验证(分目录验证篇)
  • 免责声明 - 关于我们 - 联系我们 - 广告联系 - 友情链接 - 帮助中心 - 频道导航
    Copyright © 2017 www.zgxue.com All Rights Reserved