Swagger介绍

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。而我最近做的项目用的是WebAPI,前后端完全分离，这时后端使用Swagger就能够很方便简洁的把所写的接口以及相关注释展示给前端人员，

从而方便双方的沟通，提高工作效率。

官网地址：https://swagger.io/

 

开始使用Swagger

1.首先创建一个空的WebApi项目

2.添加Swagger Nuget包 Swashbuckle

 

安装完成后开始配置Swagger

第一步：输出XML文档文件，右键点击WebAPI项目属性，找到生成一栏，并在 输出XML文档文件  选项中打钩。

 

第二步：Swagger包安装完以后会自动在WebApi项目的App_Start文件夹下生成SwaggerConfig配置类，程序初始化时会执行此配置类的代码。所以要在此配置你想要实现的功能。

初始内容如下图(博主把多余的注释代码都删掉了，并做了一点修改,所以看起来简洁一点)

 

在EnableSwagger 配置匿名方法中注册要读取的XML文件路径

 

上图中的GetXmlCommentsPath方法代码如下：

        /// <summary>
        /// 获取xml路径
        /// </summary>
        /// <returns></returns>
        protected static string GetXmlCommentsPath()
        {
            return System.String.Format(@"{0}\bin\WebApiTest.xml",System.AppDomain.CurrentDomain.BaseDirectory);
        }

注册完XML路径以后，就要开始写控制器描述和接口文档缓存的代码了

先在App_Start文件夹中新建一个CachingSwaggerProvider类，并实现ISwaggerProvider接口

代码如下

/// <summary>
    /// 读取API接口注释实现类
    /// </summary>
    public class CachingSwaggerProvider : ISwaggerProvider
    {
        private static ConcurrentDictionary<string,SwaggerDocument> _cache =
           new ConcurrentDictionary<string,SwaggerDocument>();

        private readonly ISwaggerProvider _swaggerProvider;

        /// <summary>
        /// 构造
        /// </summary>
        /// <param name="swaggerProvider"></param>
        public CachingSwaggerProvider(ISwaggerProvider swaggerProvider)
        {
            _swaggerProvider = swaggerProvider;
        }

        /// <summary>
        /// 获取文档
        /// </summary>
        /// <param name="rootUrl"></param>
        /// <param name="apiVersion"></param>
        /// <returns></returns>
        public SwaggerDocument GetSwagger(string rootUrl,string apiVersion)
        {
            var cacheKey = String.Format("{0}_{1}",rootUrl,apiVersion);
            SwaggerDocument srcDoc = null;
            //只读取一次
            if (!_cache.TryGetValue(cacheKey,out srcDoc)) {
                //AppendModelToCurrentXml();
                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 xmlpath = String.Format(@"{0}\bin\WebApiTest.xml",AppDomain.CurrentDomain.BaseDirectory);
            ConcurrentDictionary<string,string> controllerDescDict = new ConcurrentDictionary<string,string>();
            if (File.Exists(xmlpath)) {
                XmlDocument xmldoc = new XmlDocument();
                xmldoc.Load(xmlpath);
                string type = String.Empty, path = String.Empty, controllerName = String.Empty;

                string[] arrPath;
                int length = -1, cCount = "Controller".Length;
                XmlNode summaryNode = null;
                foreach (XmlNode node in xmldoc.SelectNodes("//member")) {
                    type = node.Attributes["name"].Value;
                    if (type.StartsWith("T:")) {
                        //控制器
                        arrPath = type.Split('.');
                        length = arrPath.Length;
                        controllerN