asp.net web api swagger使用總結
阿新 • • 發佈:2020-07-18
網上資料比較多 但是很零散 我從新整理一份 希望可以幫到需要的朋友
1.配置
安裝後自動生成SwaggerConfig
1.1右鍵專案→屬性→生成→選中下方的 "XML文件檔案" 然後儲存
這裡要注意 在ADO.NET裡面 我們一般會把 資料層建多一個專案,那對應專案也要打勾生成XML檔案
然後在SwaggerConfig配置
public static void Register() { var thisAssembly = typeof(SwaggerConfig).Assembly;//獲取專案檔案路徑 var baseDirectory = string.Format("{0}bin", System.Web.HttpRuntime.AppDomainAppPath); var commentsFileName = Assembly.GetExecutingAssembly().GetName().Name + ".XML"; var commentsFile = Path.Combine(baseDirectory, commentsFileName); var commentsFileName2 = "Web.Framework" + ".XML"; var commentsFile2 = Path.Combine(baseDirectory, commentsFileName2); GlobalConfiguration.Configuration .EnableSwagger(c => { //用於啟用和設定Swagger的配置資訊。 c.SingleApiVersion("v2", "API"); //單個xml檔案註釋讀取 c.IncludeXmlComments(commentsFile); c.IncludeXmlComments(commentsFile2); //swagger註釋配置 c.CustomProvider((defaultProvider) => new SwaggerCacheProvider(defaultProvider, commentsFileName)); }) .EnableSwaggerUi(c => { //用於啟用UI介面。 c.InjectJavaScript(Assembly.GetExecutingAssembly(), "connectcarweb.resources.js.swagger.js"); }); }
漢化和增加描述資訊
定義一個provider實現ISwaggerProvider介面 包含了快取 名:SwaggerCacheProvider
/// <summary> /// swagger顯示控制器的描述 /// </summary> public class SwaggerCacheProvider : 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 SwaggerCacheProvider(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; } } }
新建一個js漢化檔案swagger.js
'use strict'; /** * Translator for documentation pages. * * To enable translation you should include one of language-files in your index.html * after <script src='lang/translator.js' type='text/javascript'></script>. * For example - <script src='lang/ru.js' type='text/javascript'></script> * * If you wish to translate some new texsts you should do two things: * 1. Add a new phrase pair ("New Phrase": "New Translation") into your language file (for example lang/ru.js). It will be great if you add it in other language files too. * 2. Mark that text it templates this way <anyHtmlTag data-sw-translate>New Phrase</anyHtmlTag> or <anyHtmlTag data-sw-translate value='New Phrase'/>. * The main thing here is attribute data-sw-translate. Only inner html, title-attribute and value-attribute are going to translate. * */ 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'))); }); }, _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(); });
定義一個JS檔案,做成嵌入資源
2.使用
在WEB API 裡面 我們一般返回自定義HttpStatusCode 那swagger怎麼知道我們返回什麼Dto呢?
這裡要用到SwaggerResponse特性
/// <summary> /// 車輛管理-獲取車型列表 /// </summary> /// <returns></returns> [Route("car/get_cartypelist")] [SwaggerResponse(HttpStatusCode.OK, "獲取車型列表", typeof(List<T_CarType>))] public IHttpActionResult get_cartypelist() { List<T_CarType> list = new T_CarTypeManager().GetAllBySQL(" AND FState=1").ToList(); var oData = new { code = 200, msg = "獲取資料成功", total = list.Count, data = list }; return new ResponseJsonResult(oData, this.Request); }