Swagger使用方法詳解（WebApi）——看完不會用你打我
阿新 • • 發佈：2018-12-21
WebApi介面開發完畢後，交付給前端人員或手機端開發者時介面說明文件是必不可少的配套裝置，如果公司流程不規範大家使用口口相傳的交接方式，而且沒有改進的慾望，那你可以到此為止了。Swagger是方便測試介面，快速展示註釋內容，生成Restful風格介面文件的框架。
Swagger能成為最受歡迎的REST APIs文件生成工具之一，有以下幾個原因：
- Swagger 可以生成一個具有互動性的API控制檯，開發者可以用來快速學習和嘗試API。
- Swagger 可以生成客戶端SDK程式碼用於各種不同的平臺上的實現。
- Swagger 檔案可以在許多不同的平臺上從程式碼註釋中自動生成。
- Swagger 有一個強大的社群，裡面有許多強悍的貢獻者。
按照下述步驟操作，你就能在WebApi中使用Swagger，本文做測試用的版本v5.6.0，好好看吧，如果有可改進的地方，歡迎大家留言。
1、安裝Swagger
2、初次執行
3、新增自定義ApiController
public class PleasureController : ApiController { /// <summary> /// 獲取完整的使用者資訊 /// </summary> /// <param name="age">年齡</param> /// <param name="name">姓名</param> /// <returns>完整的使用者資訊</returns> public string GetMessage(int age,string name) { return string.Format("age={0}，name={1}", age, name); } }
4、新增實現了ISwaggerProvider介面的類
在App_Start資料夾中新增SwaggerControllerDescProvider.cs，相關程式碼如下：
namespace WebApiSwagger.Main.App_Start { /// <summary> /// 顯示swagger控制器的描述 /// </summary> public class SwaggerControllerDescProvider : ISwaggerProvider { private readonly ISwaggerProvider _swaggerProvider; private static ConcurrentDictionary<string, SwaggerDocument> _cache = new ConcurrentDictionary<string, SwaggerDocument>(); private readonly string _xml; /// <summary> /// /// </summary> /// <param name="swaggerProvider"></param> /// <param name="xml">xml文件路徑</param> public SwaggerControllerDescProvider(ISwaggerProvider swaggerProvider, string xml) { _swaggerProvider = swaggerProvider; _xml = xml; } 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; } } }
5、新增功能性js檔案
在Scripts資料夾中新增SwaggerConfig.js指令碼檔案，將其設定為“嵌入的資源”。這個js檔案的功能主要有兩個：一個是漢化，另一個是在介面上顯示控制器的描述文字。
'use strict';
window.SwaggerTranslator = {
_words: [],
translate: function () {
var $this = this;
$('[data-sw-translate]').each(function () {
$(this).html($this._tryTranslate($(this).html()));
$(this).val($this._tryTranslate($(this).val()));
$(this).attr('title', $this._tryTranslate($(this).attr('title')));
});
},
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").first().prepend('<li class="controller-summary" title="' + strSummary + '">' + strSummary + '</li>');
}
}
});
}
});
},
_tryTranslate: function (word) {
return this._words[$.trim(word)] !== undefined ? this._words[$.trim(word)] : word;
},
learn: function (wordsMap) {
this._words = wordsMap;
}
};
/* jshint quotmark: double */
window.SwaggerTranslator.learn({
"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": "從路徑",
"server returned": "伺服器返回"
});
$(function () {
window.SwaggerTranslator.translate();
window.SwaggerTranslator.setControllerSummary();
});6、修改SwaggerConfig.cs
Swagger安裝完畢後App_Start資料夾下才會有SwaggerConfig.cs檔案，修改後的SwaggerConfig.cs的程式碼如下：
public class SwaggerConfig
{
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "WebApiSwagger.Main");
//新增下述程式碼
var xmlFile = string.Format("{0}/bin/WebApiSwagger.Main.XML", System.AppDomain.CurrentDomain.BaseDirectory);
if (System.IO.File.Exists(xmlFile))
{
c.IncludeXmlComments(xmlFile);
}
c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
c.CustomProvider((defaultProvider) => new SwaggerControllerDescProvider(defaultProvider, xmlFile));
})
.EnableSwaggerUi(b =>
{
b.InjectJavaScript(Assembly.GetExecutingAssembly(), "WebApiSwagger.Main.Scripts.SwaggerConfig.js");
});
}
}
7、修改專案的“XML文件檔案”屬性
8、註釋顯示成功
9、小瑕疵及解決方法
如果看官覺得本文對您有些幫助，請點個贊、評論下鼓勵鼓勵，謝謝。