开发者社区> 优惠券活动> 正文
阿里云
为了无法计算的价值
打开APP
阿里云APP内打开

Asp.Net Core WebAPI使用Swagger时API隐藏与分组

简介: Asp.Net Core WebAPI使用Swagger时API隐藏与分组1、前言为什么我们要隐藏部分接口? 因为我们在用swagger代替接口的时候,难免有些接口会直观的暴露出来,比如我们结合Consul一起使用的时候,会将健康检查接口以及报警通知接口暴露出来,这些接口有时候会出于方便考虑,没有进行加密,这个时候我们就需要把接口隐藏起来,只有内部的开发者知道。
+关注继续查看

Asp.Net Core WebAPI使用Swagger时API隐藏与分组
1、前言
为什么我们要隐藏部分接口?

因为我们在用swagger代替接口的时候,难免有些接口会直观的暴露出来,比如我们结合Consul一起使用的时候,会将健康检查接口以及报警通知接口暴露出来,这些接口有时候会出于方便考虑,没有进行加密,这个时候我们就需要把接口隐藏起来,只有内部的开发者知道。

为什么要分组?

通常当我们写前后端分离的项目的时候,难免会遇到编写很多接口供前端页面进行调用,当接口达到几百个的时候就需要区分哪些是框架接口,哪些是业务接口,这时候给swaggerUI的接口分组是个不错的选择。

swagger的基本使用这里将不再赘述,可以阅读微软官方文档,即可基本使用

2、swaggerUI中加入授权请求
新建 HttpHeaderOperationFilter 操作过滤器,继承 Swashbuckle.AspNetCore.SwaggerGen.IOperationFilter 接口,实现 Apply 方法
复制代码
///
/// swagger请求头
///
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
复制代码
///
/// 隐藏swagger接口特性标识
///
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class HiddenApiAttribute:System.Attribute
{
}
复制代码
创建API隐藏过滤器 HiddenApiFilter 继承 Swashbuckle.AspNetCore.SwaggerGen.IDocumentFilter 接口,实现 Apply 方法
复制代码
///
/// 自定义Swagger隐藏过滤器
///
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的心跳检车接口

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

作者:一个大西瓜
出处:https://www.cnblogs.com/wyt007/

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
【ASP.NET Web API教程】2 创建各种Web API
原文 【ASP.NET Web API教程】2 创建各种Web API Chapter 2: Creating Web APIs第2章 创建各种Web API 本文引自:http://www.asp.net/web-api/overview/creating-web-apis In this chapter, you'll learn:本章你将学习: End-to-end tutorials and samples for ASP.NET Web APIASP.NET Web API的端对端教程和示例。
1037 0
【ASP.NET Web API教程】2.3 与实体框架一起使用Web API
原文:【ASP.NET Web API教程】2.3 与实体框架一起使用Web API 2.3 Using Web API with Entity Framework 2.3 与实体框架一起使用Web API 本小节是ASP.NET Web API第2章的第3小节,原文共分为7个部分,分成了7篇文章,故这里也分为7个帖子贴出,以下是本小节的第1部分 — 译者注。
1225 0
【ASP.NET Web API教程】2.3.2 创建域模型
原文:【ASP.NET Web API教程】2.3.2 创建域模型 Part 2: Creating the Domain Models 第2部分:创建域模型 本文引自:http://www.asp.
1115 0
【ASP.NET Web API教程】2.3.3 创建Admin控制器
原文:【ASP.NET Web API教程】2.3.3 创建Admin控制器 注:本文是【ASP.NET Web API系列教程】的一部分,如果您是第一次看本博客文章,请先看前面的内容。 Part 3: Creating an Admin Controller 第3部分:创建Admin控制器 本文引自:http://www.
786 0
【ASP.NET Web API教程】2.3.4 创建Admin视图
原文:【ASP.NET Web API教程】2.3.4 创建Admin视图 注:本文是【ASP.NET Web API系列教程】的一部分,如果您是第一次看本博客文章,请先看前面的内容。 Part 4: Adding an Admin View 第4部分:添加Admin视图 本文引自:http://www.
835 0
【ASP.NET Web API教程】2.3.5 用Knockout.js创建动态UI
原文:【ASP.NET Web API教程】2.3.5 用Knockout.js创建动态UI 注:本文是【ASP.NET Web API系列教程】的一部分,如果您是第一次看本博客文章,请先看前面的内容。
866 0
【ASP.NET Web API教程】2.3.6 创建产品和订单控制器
原文:【ASP.NET Web API教程】2.3.6 创建产品和订单控制器 注:本文是【ASP.NET Web API系列教程】的一部分,如果您是第一次看本博客文章,请先看前面的内容。 Part 6: Creating Product and Order Controllers 第6部分:创建产品和订单控制器 本文引自:http://www.
726 0
【ASP.NET Web API教程】2.3.7 创建首页
原文:【ASP.NET Web API教程】2.3.7 创建首页 注:本文是【ASP.NET Web API系列教程】的一部分,如果您是第一次看本博客文章,请先看前面的内容。 Part 7: Creating the Main Page 第7部分:创建首页 本文引自:http://www.
1121 0
【ASP.NET Web API教程】2.4 创建Web API的帮助页面
原文:【ASP.NET Web API教程】2.4 创建Web API的帮助页面 注:本文是【ASP.NET Web API系列教程】的一部分,如果您是第一次看本博客文章,请先看前面的内容。 2.4 Creating a Help Page for a Web API 2.
892 0
ASP.NET Web API(二):安全验证之使用HTTP基本认证
在前一篇文章ASP.NET Web API(一):使用初探,GET和POST数据中,我们初步接触了微软的REST API: Web API。 我们在接触了Web API的后就立马发现了有安全验证的需求,所以这篇文章我们先来讨论下安全验证一个最简单的方法:使用HTTP基本认证。
881 0
+关注
优惠券活动
阿里云优惠码阿里云推荐券bieryun.com
文章
问答
文章排行榜
最热
最新
相关电子书
更多
Java Spring Boot开发实战系列课程【第15讲】:Spring Boot 2.0 API与Spring REST Docs实战
立即下载
阿里云 API 精选手册(Alibaba Cloud API Playbook)
立即下载
API 网关实践
立即下载