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(, 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时API隐藏与分组的更多相关文章

  1. ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

    引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...

  2. ASP.NET Core WebApi使用Swagger生成api

    引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...

  3. ASP.NET Core WebApi使用Swagger生成api说明文档

    1. Swagger是什么? Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件 ...

  4. 【转】ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

    原文链接:https://www.cnblogs.com/yilezhu/p/9241261.html 引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必 ...

  5. ASP.NET Core WebApi使用Swagger生成API说明文档【xml注释版】

    ⒈新建ASP.NET Core WebAPi项目 ⒉添加 NuGet 包 Install-Package Swashbuckle.AspNetCore ⒊Startup中配置 using System ...

  6. ASP.NET Core WebApi使用Swagger生成API说明文档【特性版】

    ⒈新建ASP.NET Core WebAPi项目 ⒉添加 NuGet 包 Install-Package Swashbuckle.AspNetCore ⒊Startup中配置 using System ...

  7. 三分钟学会 ASP.NET Core WebApi使用Swagger生成api说明文档

    什么是Swagger?为啥要用Swagger? Swagger可以从不同的代码中,根据注释生成API信息,Swagger拥有强大的社区,并且对于各种语言都支持良好,有很多的工具可以通过swagger生 ...

  8. Asp.net core WebApi 使用Swagger生成帮助页

    最近我们团队一直进行.net core的转型,web开发向着前后端分离的技术架构演进,我们后台主要是采用了asp.net core webapi来进行开发,开始每次调试以及与前端人员的沟通上都存在这效 ...

  9. Asp.net core WebApi 使用Swagger生成帮助页实例

    最近我们团队一直进行.net core的转型,web开发向着前后端分离的技术架构演进,我们后台主要是采用了asp.net core webapi来进行开发,开始每次调试以及与前端人员的沟通上都存在这效 ...

随机推荐

  1. BZOJ_2595_[Wc2008]游览计划_斯坦纳树

    BZOJ_2595_[Wc2008]游览计划_斯坦纳树 题意: 分析: 斯坦纳树裸题,有几个需要注意的地方 给出矩阵,不用自己建图,但枚举子集转移时会算两遍,需要减去当前点的权值 方案记录比较麻烦,两 ...

  2. Eureka的基本功能和用法

    1.基础架构 eueka按逻辑上可以划分为3个模块,eureka-server,service-provider,service-consumereureka-server:服务端,提供服务注册和发现 ...

  3. gulp、browsersync代理跨域

    //gulpfile.js "use strict"; const gulp = require("gulp"), newer = require(" ...

  4. 【工具篇】接口测试神器 -- Postman 入门教程

    一.Postman概述 (1)工具介绍 Postman是一个接口测试工具,一款非常流行的API调试工具.在做接口测试的时候,Postman相当于一个客户端,它可以模拟用户发起的各类HTTP请求,将请求 ...

  5. 从壹开始 [ Nuxt.js ] 之二 || 项目搭建 与 接口API

    前言 哈喽大家周一好,今天的内容比较多,主要就是包括:把前端页面的展示页给搭出来,然后调通接口API,可以添加数据,这两天我也一直在开发,本来想一篇一篇的写,发现可能会比较简单,就索性把项目搭建的过程 ...

  6. 漫谈“采样”(sampling)

      越学越懵了,计算机中是怎么进行采样的,用了这么久的 rand() 函数,到现在才知道是怎么做的. 从均匀分布中采样   计算机中通过线性同余发生器(linear congruential gene ...

  7. python接口自动化(十九)--Json 数据处理---实战(详解)

    简介 上一篇说了关于json数据处理,是为了断言方便,这篇就带各位小伙伴实战一下.首先捋一下思路,然后根据思路一步一步的去实现和实战,不要一开始就盲目的动手和无头苍蝇一样到处乱撞,撞得头破血流后而放弃 ...

  8. 安全性测试入门:DVWA系列研究(一):Brute Force暴力破解攻击和防御

    写在篇头: 随着国内的互联网产业日臻成熟,软件质量的要求越来越高,对测试团队和测试工程师提出了种种新的挑战. 传统的行业现象是90%的测试工程师被堆积在基本的功能.系统.黑盒测试,但是随着软件测试整体 ...

  9. 《k8s-1.13版本源码分析》-源码调试

    源码分析系列文章已经开源到github,地址如下: github:https://github.com/farmer-hutao/k8s-source-code-analysis gitbook:ht ...

  10. CenOS_命令帮助

    1.帮助 1.1man 基本语法: man[命令或配置文件](功能描述:获得帮助信息) 如:man ll 1.2help 基本语法: help 命令 (功能描述:获得 shell 内置命令的帮助信息) ...