Asp.Net WebApi Swagger终极搭建
【PS：原文手打，转载说明出处，博客园】
关于为什么用Swagger
目前稍微有点规模的公司，已经从原先的瀑布流开发到了敏捷开发，实现前后端分离，为此后端工程师只关注写好Api即可，那程序员最讨厌的就是写Api文档了，故而产生了Swagger。
Swagger原理
Swagger就是利用反射技术遍历所有Api接口，并且从xml文件中读取注释，在利用Swagger内置的模板组合html显示至客户端实现接口可视化，并且可调用。
Asp.net WebApi Swagger集成
1：vs2017，新建web项目，选择WebApi
2：删除Views、Scripts、Models、fonts、Content、Areas目录
3：删除RouteConfig.cs、FilterConfig.cs、BundleConfig.cs
4：删除HomeController.cs
5：Global.asax中删除异常代码
6：nuget搜索Swagger,安装 Swashbuckle
7：右键项目——》属性——》生成——》输出——》勾选XML文档文件——》保存
8：修改SwaggerConfig.cs
新增方法，释放c.IncludeXmlComments(GetXmlCommentsPath());的注释（注意：例如返回值为对象，然后又不在同一个项目，则需要多次调用）
private static string GetXmlCommentsPath() { return System.String.Format(@"{0}\bin\{项目名称}.XML", System.AppDomain.CurrentDomain.BaseDirectory); }
9：然后在url地址中:例如：http://localhost:port/swagger即可
Swagger进阶
1：当有dto项目时，此时dto也需要把注释打到客户端，注意dto项目也参考上面第7点生成xml文件，复制第8点的方法
2：Swagger新增Header信息，在上方注释的地方加入：c.OperationFilter<HttpHeaderFilter>(); 拷贝下方代码
public class HttpHeaderFilter : IOperationFilter { public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) { if (operation.parameters == null) operation.parameters = new List<Parameter>(); var filterPipeline = apiDescription.ActionDescriptor.GetFilterPipeline(); //判断是否添加权限过滤器 var isAuthorized = filterPipeline.Select(filterInfo => filterInfo.Instance) .Any(filter => filter is ErpFilterAttribute); //判断是否允许匿名方法 //var allowAnonymous = apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any(); if (isAuthorized) { operation.parameters.Add(new Parameter { name = "AppId", @in = "header", description = "应用ID（机构编号）", required = false, type = "string" }); operation.parameters.Add(new Parameter { name = "Version", @in = "header", description = "版本号", required = false, type = "string" }); operation.parameters.Add(new Parameter { name = "Ts", @in = "header", description = "时间戳", required = false, type = "string" }); operation.parameters.Add(new Parameter { name = "Lang", @in = "header", description = "语言包", required = false, type = "string" }); operation.parameters.Add(new Parameter { name = "Sign", @in = "header", description = "签名", required = false, type = "string" }); return; } } }
3：注释的用法
注释的用法，在API接口中"///"三斜杠注释的summary为接口名注释，summary下回车<remarks>为备注，注意每个字段的注释必须要全面，否则无法显示完全
参考代码如下
/// <summary> /// 角色 分页列表 /// </summary> /// <remarks> /// Code返回值说明： /// /// 错误码地址：http://xxxx.com/ /// /// </remarks> /// <param name="conditionModel">分页查询条件</param> /// <returns></returns> [HttpGet, Route("api/ClientRoles")] public OutputModel<PagingOutputModel<List<BaseRoleDto>>> GetRoleList([FromUri]PagingInputModel conditionModel) { return null; }
4：显示控制器注释
新建：CachingSwaggerProvider.cs，代码如下 注意Mike.Merchant.WebApi.XML需要替换成你本地的工程目录
using System; using System.Collections.Concurrent; using System.Collections.Generic; using System.Linq; using System.Web; using System.Xml; using Swashbuckle.Swagger; using System.IO; namespace Mike.Merchant.WebApi { 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)) { 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/Mike.Merchant.WebApi.XML", System.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; 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_show.js，代码如下
var ControllerSummary = function () { var urlval = $("#input_baseUrl").val() $.ajax({ type: "get", async: true, url: urlval, dataType: "json", success: function (data) { var summaryDict = data.ControllerDesc; var id, controllerName, strSummary; $("#resources_container .resource").each(function (i, item) { id = $(item).attr("id"); if (id) { controllerName = id.substring(9); strSummary = summaryDict[controllerName]; if (strSummary) { $(item).children(".heading").children(".options").prepend('<li style="color:red;" class="controller-summary" title="' + strSummary + '">' + strSummary + '</li>'); } } }); } }); } ControllerSummary()
打开SwaggerConfig.cs 代码如下
注意代码：c.InjectJavaScript(thisAssembly, "Mike.Merchant.WebApi.Scripts.swagger_show.js");
后面的这个为工程目录.文件夹.js。
GlobalConfiguration.Configuration .EnableSwagger(c => { c.SingleApiVersion("v1", "Api文档"); c.OperationFilter<HttpHeaderFilter>(); c.IncludeXmlComments(GetXmlCommentsPath()); //c.IncludeXmlComments(GetDtoXmlCommentsPath()); c.CustomProvider((defaultProvider) => new CachingSwaggerProvider(defaultProvider)); }) .EnableSwaggerUi(c => { c.DocumentTitle("Api文档"); c.InjectJavaScript(thisAssembly, "Mike.Merchant.WebApi.Scripts.swagger_show.js"); });
图片展示
