swagger的一个最大的优点是能实时同步api与文档,但有些时候我们不想全部公开接口,而要隐藏或屏蔽一些接口类或方法,swagger也是支持的,只需要设置一下DocumentFilter方法。
第一步:在SwaggerConfig.cs配置文件中设置DocumentFileter
public class SwaggerConfig { public static void Register() { var thisAssembly = typeof(SwaggerConfig).Assembly; GlobalConfiguration.Configuration .EnableSwagger(c => { //设置版本和接口描述 c.SingleApiVersion("v1", "接口文档描述"); //在接口类、方法标记属性 [HiddenApi],可以阻止【Swagger文档】生成 c.DocumentFilter<HiddenApiFilter>(); //c.CustomProvider((defaultProvider) => newCachingSwaggerProvider(defaultProvider)); //设置接口描述xml路径地址 c.IncludeXmlComments(string.Format("{0}/Doc/CYP.GMS.CooperativeBusiness.WebService.XML", System.AppDomain.CurrentDomain.BaseDirectory)); c.IncludeXmlComments(string.Format("{0}/Doc/CYP.GMS.CooperativeBusiness.Model.XML", System.AppDomain.CurrentDomain.BaseDirectory)); }) .EnableSwaggerUi(c => { //c.DocumentTitle("My Swagger UI"); //c.InjectStylesheet(containingAssembly, "Swashbuckle.Dummy.SwaggerExtensions.testStyles1.css"); //路径规则,项目命名空间.文件夹名称.js文件名称 //c.InjectJavaScript(thisAssembly, "WebAPI.Scripts.swaggerui.swagger_lang.js"); }); } }
第二步:在SwaggerConfig.cs配置文件里最后面增加HiddenApiFilter类
/// <summary> /// 隐藏接口,不生成到swagger文档展示 /// 注意:如果不加[HiddenApi]标记的接口名称和加过标记的隐藏接口名称相同,则该普通接口也会被隐藏不显示,所以建议接口名称最好不要重复 /// </summary> [AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)] public partial class HiddenApiAttribute : Attribute { } public class HiddenApiFilter : IDocumentFilter { /// <summary> /// 重写Apply方法,移除隐藏接口的生成 /// </summary> /// <param name="swaggerDoc">swagger文档文件</param> /// <param name="schemaRegistry"></param> /// <param name="apiExplorer">api接口集合</param> public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer) { foreach (ApiDescription apiDescription in apiExplorer.ApiDescriptions) { if (Enumerable.OfType<HiddenApiAttribute>(apiDescription.GetControllerAndActionAttributes<HiddenApiAttribute>()).Any()) { string key = "/" + apiDescription.RelativePath; if (key.Contains("?")) { int idx = key.IndexOf("?", StringComparison.Ordinal); key = key.Substring(0, idx); } swaggerDoc.paths.Remove(key); } } } }
第三步:API接口调用实例
注意:如果不加[HiddenApi]标记的接口名称和加过标记的隐藏接口名称相同,则该普通接口也会被隐藏不显示,所以建议接口名称最好不要重复
/// <summary> /// 隐藏接口方法生成文档(添加[HiddenApi]特性) /// </summary> /// <param name="value"></param> /// <returns></returns> [HiddenApi] [Route("HideApi")] [HttpGet] public HttpResponseMessage HideApi(string value) { return Request.CreateResponse(HttpStatusCode.OK, new { errorCode = "0", value = value }); }