你的位置:首页 > ASP.net教程

[ASP.net教程]ASP.NET WebApi 文档Swagger中度优化


本文版权归博客园和作者吴双本人共同所有,转载和爬虫请注明原文地址: www.cnblogs.com/tdws

  写在前面

在后台接口开发中,接口文档是必不可少的。在复杂的业务当中和多人对接的情况下,简单的接口文档又不能满足需求,试想你的单应用后台有几十个模块,几百甚至更多的接口,又有上百个ViewModel。怎么能让人用起来更顺手更明了?本篇介绍第一步的中度优化,下一篇将分享下一阶段的深度优化。

 第一篇:ASP.NET WebApi 文档Swagger中度优化

1.上手使用

2.Controller注释读取和汉化

3.Actionf group by 分组

4.通过exe整合xxxModel.

5.通过批处理命令在生成后调用exe

 第二篇:ASP.NET WebApi 文档Swashbuckle.Core与SwaggerUI深度定制

Swagger是一款完全开源的文档工具,其优点在于前后端的完整分离,他们之间的契约就是Json的数据格式。其后台项目就是github中的Swashbuckle。其前台项目就是github中的SwaggerUI。有一点需要注意的是,如果你直接从nuget安装Swashbuckle的话,你也并不想做更多的定制化,那么UI界面你完全不需要处理,因为所有的资源Resources都是嵌入到Swashbuckle.dll当中的,你可以在vs对象管理器中查看到Resources,如下图,是不是又复习了dll的作用了呢?其中还可以包含css,js,image等资源:

看下本次分享的效果图吧,只选了四个Controller做展示,个人觉得还是比较明了的吧,如果模块和控制器多了起来,就会深刻体会到好处:

 

  先学会上手使用

  nuget中搜索Swashbuckle并安装到你的WebApi项目中,其他的不用安装哦。

  安装完成后你的App_Start中会多一个SwaggerConfig这样一个配置文件,这个文件是Swagger为我们留下的配置入口,我们可以根据其中的注释和介绍做很多事情。然后我把Swagger单独出来一个文件夹,直接将配置类拖进去,如下效果:

下一步配置你的项目属性,在其生成选项当中,选择下图配置:

配置文件中主要有两个入口:EnableSagger和EnableSwaggerUi,顾名思义,配置其后台项和前台项。

找到下面这行代码,传入你所需的两个字符串

下一步找到Include

 c.Includestring.Format("{0}/bin/SwaggerDemo.", System.AppDomain.CurrentDomain.BaseDirectory));

至此基本就可以显示你的接口了,请访问:localhost:xxxx/swagger   你可能会问为什么我没有添加页面也能展示,这就是因为页面和其路由设置都在dll中了!下面这段源码揭示了为什么可以直接通过路由访问到你的swagger主页,当然你也可以不必关心下面这段:

public void EnableSwaggerUi(      string routeTemplate,      Action<SwaggerUiConfig> configure = null)    {      var config = new SwaggerUiConfig(_discoveryPaths, _rootUrlResolver);      if (configure != null) configure(config);      _httpConfig.Routes.MapHttpRoute(        name: "swagger_ui" + routeTemplate,        routeTemplate: routeTemplate,        defaults: null,        constraints: new { assetPath = @".+" },        handler: new SwaggerUiHandler(config)      );      if (routeTemplate == DefaultRouteTemplate)      {        _httpConfig.Routes.MapHttpRoute(          name: "swagger_ui_shortcut",          routeTemplate: "swagger",          defaults: null,          constraints: new { uriResolution = new HttpRouteDirectionConstraint(HttpRouteDirection.UriResolution) },          handler: new RedirectHandler(_rootUrlResolver, "swagger/ui/index"));      }    }

 

 

 Controller注释读取

默认情况下,Controller注释是没有读取的。那么你需要通过如下配置来达到目的,增加这样一个类,不用问为什么。下面这段代码也是参考了一位园友的。汉化我也没必要讲了,他已经说的很详细了。

 
public class CachingSwaggerProvider : ISwaggerProvider  {    private static ConcurrentDictionary<string, SwaggerDocument> _cache =      new ConcurrentDictionary<string, SwaggerDocument>();    private readonly ISwaggerProvider _swaggerProvider;    public CachingSwaggerProvider(ISwaggerProvider swaggerProvider)    {      _swaggerProvider = swaggerProvider;    }    public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)    {      var cacheKey = String.Format("{0}_{1}", rootUrl, apiVersion);      SwaggerDocument srcDoc = null;      //只读取一次      if (!_cache.TryGetValue(cacheKey, out srcDoc))      {        //AppendModelToCurrent        srcDoc = _swaggerProvider.GetSwagger(rootUrl, apiVersion);        srcDoc.vendorExtensions = new Dictionary<string, object> { { "ControllerDesc", GetControllerDesc() }, { "", "" } };        _cache.TryAdd(cacheKey, srcDoc);      }      return srcDoc;    }    /// <summary>    /// 从API文档中读取控制器描述    /// </summary>    /// <returns>所有控制器描述</returns>    public static ConcurrentDictionary<string, string> GetControllerDesc()    {      string "{0}/bin/SwaggerDemo.", AppDomain.CurrentDomain.BaseDirectory);      ConcurrentDictionary<string, string> controllerDescDict = new ConcurrentDictionary<string, string>();      if (File.Exists(= new string type = String.Empty, path = String.Empty, controllerName = String.Empty;        string[] arrPath;        int length = -1, cCount = "Controller".Length;        = null;        foreach (in "//member"))        {          type = node.Attributes["name"].Value;          if (type.StartsWith("T:"))          {            //控制器            arrPath = type.Split('.');            length = arrPath.Length;            controllerName = arrPath[length - 1];            if (controllerName.EndsWith("Controller"))            {              //获取控制器注释              summaryNode = node.SelectSingleNode("summary");              string key = controllerName.Remove(controllerName.Length - cCount, cCount);              if (summaryNode != null && !String.IsNullOrEmpty(summaryNode.InnerText) && !controllerDescDict.ContainsKey(key))              {                controllerDescDict.TryAdd(key, summaryNode.InnerText.Trim());              }            }          }        }      }      return controllerDescDict;    }  }

并且在SwaggerConfig找到下面这行代码:

 c.CustomProvider((defaultProvider) => new CachingSwaggerProvider(defaultProvider));

至此  Action分组展示

下面这个功能通过我们自定义的Attribute来实现。先往下看,不用问为什么,功能实现后自然明白啦:

 /// <summary>  /// Controller描述信息  /// </summary>  [AttributeUsage(AttributeTargets.Class, AllowMultiple = false)]  public class ControllerGroupAttribute : Attribute  {    /// <summary>    /// 当前Controller所属模块 请用中文    /// </summary>    public string GroupName { get; private set; }    /// <summary>    /// 当前controller用途  请用中文    /// </summary>    public string Useage { get; private set; }    /// <summary>    /// Controller描述信息 构造    /// </summary>    /// <param name="groupName">模块名称</param>    /// <param name="useage">当前controller用途</param>    public ControllerGroupAttribute(string groupName, string useage)    {      if (string.IsNullOrEmpty(groupName) || string.IsNullOrEmpty(useage))      {        throw new ArgumentNullException("groupName||useage");      }      GroupName = groupName;      Useage = useage;    }  }

给你的每个Controller加上这个Attribute:

 

 

为了分模块,我做了这种描述,其他内容不一一描述:

在Swagger找到GroupActionsBy方法:

并且按照你所设定的分组Attribute来分组排序,最终达到我们想要的效果,请仔细阅读代码,就自然理解了:

 c.GroupActionsBy(apiDesc => apiDesc.GetControllerAndActionAttributes<ControllerGroupAttribute>().Any() ? 
apiDesc.GetControllerAndActionAttributes<ControllerGroupAttribute>().First().GroupName + "_" +
apiDesc.GetControllerAndActionAttributes<ControllerGroupAttribute>().First().Useage : "无模块归类");

   合并Model层的

上面的效果,你可能看不到Model层的描述信息(如果你的实体没有在其他层是会正常显示的)。但是Model分层了,怎么能展示呢,我目前给出的解决方案是合并

通过相对路径,将model层的

static void Main(string[] args)    {      AppendModelToCurrent"");      //Console.ReadLine();    }    public static void AppendModelToCurrent= new + @"/bin/Model.");      var membersNode = "members")[0]; //Model层Members节点      @"/bin/SwaggerDemo.");      var currentMembersNode = "members")[0]; //API层Members节点      for (int i = 0; i < membersNode.ChildNodes.Count; i++)      {        var memberNode = membersNode.ChildNodes[i];        currentMembersNode.AppendChild(memberNode.Clone());        if (memberNode.HasChildNodes)        {          memberNode.AppendChild(memberNode.ChildNodes[0]);        }      }      + @"/bin/SwaggerDemo.");    }

至于我为什么要取路径时选择appDomain,是因为我准备把该exe文件放置到webAPI项目的根目录下,这样取到的路径就是API项目的物理路径,如果把物理路径写死,很烦的,你懂的,因为发布或者到其他人电脑中,物理路径基本就变了。这段代码的主要功能就是把Model层中所生成的

 并且,为了不用每次都手动调用exe文件,我使用批处理命令,在每次项目生成后,自动执行exe.

Swagger的前后端分离,靠json格式的契约,你可以在network中查看json结果,下一篇深度定制分享将会用到它。

 

 

   写在最后

 本篇多数是配置化的内容,只不过在实际操作的时候,面对不同情况,我们希望能得到更好的结果。动手尝试一下吧,如果有问题和不足的地方,欢迎留言探讨,万一你以后用上了呢,不,应该说WebApi文档你是一定用得上。下一篇,将会更深一步的优化,让我们拿到源码后,无论有什么特别的需求,都能自己亲手修改,而不被蒙蔽在dll中。

如果我的点滴分享对你有点滴帮助,欢迎点下方红色按钮关注,我将持续分享。也欢迎为我,也为你自己点赞。