當前位置：首頁 > 编程语言 > asp.net >内容正文

asp.net

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

發布時間：2023/12/4 asp.net 29 豆豆

生活随笔收集整理的這篇文章主要介紹了 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的心跳檢車接口
但是在接口文檔中并沒有顯示出來

原文地址：https://www.cnblogs.com/wyt007/p/10650974.html

.NET社區新聞，深度好文，歡迎訪問公眾號文章匯總 http://www.csharpkit.com

總結

以上是生活随笔為你收集整理的Asp.Net Core WebAPI使用Swagger时API隐藏与分组的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。

上一篇： Visual Studio 2019 使
下一篇：基于Kubernetes 构建.NET