Asp.Net MVC專案整合Swagger
公司最近的專案使用mvc+webapi，採取前後端分離的方式，後臺提供API介面給前端開發人員。這個過程中遇到一個問題後臺開發人員怎麼提供介面說明文件給前端開發人員,之前一直使用的是word文件方式進行交流，效率低下而且不利於維護。為了解決這個問題，經過一番研究，引起我注意的有兩種方案。1.微軟自帶的Microsoft.AspNet.WebApi.HelpPage 2.swagger（我比較喜歡戲稱為“絲襪哥”）
最先嚐試的是微軟自帶的方案，由於介面實在是比較一般，於是轉向了第二種方案,經過大半天大搗鼓，最終效果如下：
1.列出所有API控制器和控制器描述
2.列出action和描述
3.直觀的介面測試
達到這幾點目標，已經滿足專案使用。
使用swagger
1.建立webapi專案解決方案
2.引用swagger nuget包
引入Swashbuckle一個包即可，有些教程說要引入和Swagger.Net.UI，其實功能重複了（後面會解釋）。
引入後，專案App_Start下會多一個檔案：
3.新增介面註釋
完成上面三部執行專案，可以看到介面描述已經生成，瀏覽地址http://xxx/Swagger。但是沒有介面的註釋，當時決定引入Api管理工具就是看中了註釋功能，下面新增介面註釋
專案屬性->生成，勾選生成xml文件檔案（有些太古老的WebSite專案不支援註釋功能，因為根本沒有生成xml這一個選項）
修改SwaggerConfig檔案
給介面添加註釋，即可看到引數及方法描述了。
漢化及問題解決
經過上面的操作，已經完成了所需功能。但是還有幾點問題需要完善
1.介面的說明都是英文的需要進行漢化
2.控制器沒有描述
3.介面過多每次生成速度比較慢
1.漢化步驟
在SwaggerConfig配置檔案中有這麼一段程式碼
.EnableSwaggerUi(c =>{ //c.InjectJavaScript(thisAssembly, "Swashbuckle.Dummy.SwaggerExtensions.testScript1.js") });
這段程式碼的作用是向頁面輸出引用Swashbuckle.Dummy.SwaggerExtensions.testScript1.js檔案，或許會疑問js檔案路徑為什麼這麼奇怪。那是因為Swagger將資原始檔都嵌入到dll中了，我們常用的資原始檔都是以內容的方式放在專案中的，我們也可以以嵌入的資源方式引入到專案中
這也是上面不引入Swagger.Net.UI,頁面也能正常出來的原因。資原始檔都被打包到dll中了，使用反編譯工具reflector。來反編譯一下Swashbuckle.Core.dll
弄清楚了實現原理，現在來實現漢化。新增自己的中文語言包，和轉換js，實現邏輯參考swagger原始碼。
//c.InjectJavaScript(thisAssembly, "Swashbuckle.Dummy.SwaggerExtensions.testScript1.js"); //路徑規則，專案名稱空間.資料夾名稱.js檔名稱 c.InjectJavaScript(thisAssembly, "BWebFoowwSoftStatistic.Content.js.SwaggerUI.Swagger_lang.js");
/// <summary> /// 中文轉換 /// </summary> var SwaggerTranslator = (function () { //定時執行檢測是否轉換成中文,最多執行500次 即500*50/1000=25s var iexcute = 0, //中文語言包 _words = { "Warning: Deprecated": "警告：已過時", "Implementation Notes": "實現備註", "Response Class": "響應類", "Status": "狀態", "Parameters": "引數", "Parameter": "引數", "Value": "值", "Description": "描述", "Parameter Type": "引數型別", "Data Type": "資料型別", "Response Messages": "響應訊息", "HTTP Status Code": "HTTP狀態碼", "Reason": "原因", "Response Model": "響應模型", "Request URL": "請求URL", "Response Body": "響應體", "Response Code": "響應碼", "Response Headers": "響應頭", "Hide Response": "隱藏響應", "Headers": "頭", "Try it out!": "試一下！", "Show/Hide": "顯示/隱藏", "List Operations": "顯示操作", "Expand Operations": "展開操作", "Raw": "原始", "can't parse JSON. Raw result": "無法解析JSON. 原始結果", "Model Schema": "模型架構", "Model": "模型", "apply": "應用", "Username": "使用者名稱", "Password": "密碼", "Terms of service": "服務條款", "Created by": "建立者", "See more at": "檢視更多：", "Contact the developer": "聯絡開發者", "api version": "api版本", "Response Content Type": "響應Content Type", "fetching resource": "正在獲取資源", "fetching resource list": "正在獲取資源列表", "Explore": "瀏覽", "Show Swagger Petstore Example Apis": "顯示 Swagger Petstore 示例 Apis", "Can't read from server. It may not have the appropriate access-control-origin settings.": "無法從伺服器讀取。可能沒有正確設定access-control-origin。", "Please specify the protocol for": "請指定協議：", "Can't read swagger JSON from": "無法讀取swagger JSON於", "Finished Loading Resource Information. Rendering Swagger UI": "已載入資源資訊。正在渲染Swagger UI", "Unable to read api": "無法讀取api", "from path": "從路徑", "Click to set as parameter value": "點選設定引數", "server returned": "伺服器返回" }, //定時執行轉換 _translator2Cn = function () { if ($("#resources_container .resource").length > 0) { _tryTranslate(); } if ($("#explore").text() == "Explore" && iexcute < 500) { iexcute++; setTimeout(_translator2Cn, 50); } }, //設定控制器註釋 _setControllerSummary = function () { $.ajax({ type: "get", async: true, url: $("#input_baseUrl").val(), 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 class="controller-summary" title="' + strSummary + '">' + strSummary + '</li>'); } } }); } }); }, //嘗試將英文轉換成中文 _tryTranslate = function () { $('[data-sw-translate]').each(function () { $(this).html(_getLangDesc($(this).html())); $(this).val(_getLangDesc($(this).val())); $(this).attr('title', _getLangDesc($(this).attr('title'))); }); }, _getLangDesc = function (word) { return _words[$.trim(word)] !== undefined ? _words[$.trim(word)] : word; }; return { Translator: function () { document.title = "API描述文件"; $('body').append('<style type="text/css">.controller-summary{color:#10a54a !important;word-break:keep-all;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:250px;text-align:right;cursor:default;} </style>'); $("#logo").html("介面描述").attr("href", "/Home/Index"); //設定控制器描述 _setControllerSummary(); _translator2Cn(); } } })(); //執行轉換 SwaggerTranslator.Translator();
2.控制器描述和介面文件快取
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/SwaggerDemo.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; } }
c.CustomProvider((defaultProvider) => new CachingSwaggerProvider(defaultProvider));
上面漢化的js中的方法_setControllerSummary通過讀取ControllerDesc屬性設定了控制器的描述，至此專案可以無憂使用介面描述文件。
3.action 方法名稱相同處理
根據錯誤提示 很快發現 某位大神 同樣的介面名 傳遞了不同引數，導致了這個錯誤，解決方式：
c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
4.一個Controller不支援多個Get/Post請求問題，修改WebApiConfig.cs
5.Date時間型別不對生成Json格式不對的問題
WebApi自帶json序列化對遇到時間日期欄位的時候，到前端獲取的格式總是為“ 2016-07-14T15:32:44”，中間總是會帶一個T,顯然不是很友好，解決方案如下：
6swagger 問題2.序列化出來的JSON NULL 值處理。
先上圖
等了好半天 一直不出來 開啟F12一看原來有錯，萬能的網友幫了我，原來問題出在http://localhost:58303/swagger/docs/v1這個JSON資源上面，
序列化出來的JSON，包含了為NULL的欄位，導致swagger-ui-min-js出現異常。
進一步分析是因為我專案使用的newtonsoft.json這個庫的配置導致，應該忽略為NULL的欄位，
對應解決辦法如圖： settings.NullValueHandling = NullValueHandling.Ignore;
總結：
規範化api的編寫和註釋，以及標準化文件，對於團隊的開發效率有很大的提升，也有利於專案的維護。使用線上介面文件後，方便前後端工程師溝通，測試人員測試只需要在頁面輸入引數，點選呼叫就可以看到呼叫結果。