Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解

站长资源 2024/11/30 佚名

2 0 1

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,api,注解

广告合作：本站广告合作请联系QQ：858582 申请时备注：广告合作（否则不回）
免责声明：本站资源来自互联网收集,仅供用于学习和交流,请遵循相关法律法规,本站一切资源不代表本站立场,如有侵权、后门、不妥请联系本站删除！

评论“Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解”

暂无评论...

www.wwsws.com 伏龙阁资源网

39,976影音资源

44,792技术资源

21,817软件资源

651,128站长资源

Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解

如何利用FluentMigrator实现数据库迁移

.NET Corek中Git的常用命令及实战演练

评论“Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解”

RTX 5090要首发性能要翻倍！三星展示GDDR7显存

更新日志

友情链接

Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解

如何利用FluentMigrator实现数据库迁移

.NET Corek中Git的常用命令及实战演练

评论“Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解”

RTX 5090要首发 性能要翻倍！三星展示GDDR7显存

更新日志

友情链接

RTX 5090要首发性能要翻倍！三星展示GDDR7显存