.Net swagger初探(配置swagger汉化及请求头设置系统发布)

.Net swagger初探(配置swagger汉化及请求头设置系统发布)

首先肯定是需要一个API的项目这里就不详细介绍了下面主要介绍一下swagger的使用
1:右键点击项目引用管理NuGet程序包找到Swashbuckle下载

下载之后你会发现在APP_start中会多处一个文件SwaggerConfig这里就是swagger的配置项之后的设置都需要在其中操作，
2：接下来配置输出文件路径

这里值得注意的一点是配置中要选择Release否侧你会发现在发布的时候你的发布文件中是不包含.xml这个文件的
3:到这里大家运行项目地址栏中加上swagger就可以看到swagger文档了

好的文档生成了很完美；
但是
大家要明白文档作用主要是给别人阅读方便而我们现在生成的文档是很难让人看懂的；
这里就要大家规范自己的代码一定要在方法及接口中加必要的注解，这里推荐给大家一个工具StyleCode 同样通过Nuget搜索StyleCop.Analyzers就可以使用了 其中涉及到一些自定义的操作之后需要会给大家介绍的；

接口规范之后大家也会发现想要的注解并没有显示出来是因为swagger本身是英文版的不支持中文注解这里就需要我们做一下汉话的操作
4：新建类SwaggerCacheProvider继承ISwaggerProvider
代码实现

        /// SwaggerCacheProvider.
        /// </summary>
        /// <param name="swaggerProvider">swaggerProvider.</param>
        /// <param name="xml">xml文档路径.</param>
        public SwaggerCacheProvider(ISwaggerProvider swaggerProvider, string xml)
        {
            this.swaggerProvider = swaggerProvider;
            this.xml = xml;
        }        /// <inheritdoc/>
        public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)
        {
            var cacheKey = string.Format("{0}_{1}", rootUrl, apiVersion);
            SwaggerDocument srcDoc = null;            // 只读取一次.
            if (!cache.TryGetValue(cacheKey, out srcDoc))
            {
                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 ConcurrentDictionary<string, string> GetControllerDesc()
        {
            string xmlpath = xml;
            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;
                        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;
        }
    }

然后新建一个swagger.js文件并设置为嵌套的资源我的浏览器有问题这里暂时先不上代码了 大家可以在网上有很多这个代码

接下来配置一下SwaggerConfig

 c.IncludeXmlComments(string.Format("{0}/bin/GMExpenseAPI.xml", System.AppDomain.CurrentDomain.BaseDirectory));
c.CustomProvider((defaultProvider) => new SwaggerCacheProvider(defaultProvider, string.Format("{0}/bin/GMExpenseAPI.XML", System.AppDomain.CurrentDomain.BaseDirectory)));
 c.OperationFilter<HttpAuthHeaderFilter>();

c.InjectJavaScript(System.Reflection.Assembly.GetExecutingAssembly(), "GMExpenseAPI.swagger.js");

这样就完成了汉化就可以看到文档中出现了明显的注释内容

很多的接口我们都会添加验证方式如果是请求头中的如何在swagger中增加呢 我们来继续操作
新建类HttpAuthHeaderFilter继承IOperationFilter

到这里所有的设置就结束了 如果哪里有不足的地方或者 大家有什么问题可以留言给我；