ASP.NET WebAPI 使用Swagger使用方法 ，不是.net core
阿新 • • 發佈：2020-07-14
描述 ASP.NET WebAPI這塊沒有文件，主要是一些老的專案，新的.net coreweb apiswagger很方便，下面主要是對ASP.NET WebAPI使用 swagger操作
一，swagger 引用
新增NuGet包
第二步：修改SwaggerConfig.cs
預設會在App_Start下面新增 swaggerconfig.cs
如 api 版本號，title
第三步：建立專案XML註釋文件
右鍵專案→屬性→生成→選中下方的 "XML文件檔案" 然後儲存
配置啟用：
在
GlobalConfiguration.Configuration
下面新增
c.IncludeXmlComments(string.Format("{0}/WebApi.XML", System.AppDomain.CurrentDomain.BaseDirectory));//設定xml地址
在EnableSwaggerUi下新增DocumentTitle
.EnableSwaggerUi(c =>
{
c.DocumentTitle("My webapi");
第四步：啟動專案
地址：http://localhost:xxx/swagger
預設都是英文的，這就是ASP.NET WebAPI 使用Swagger不好之處要自己漢化
第五步：漢化及controller說明
第一步：定義一個provider實現ISwaggerProvider介面 包含了快取 名：SwaggerCacheProvider
using Swashbuckle.Swagger; using System.Collections.Concurrent; using System.Collections.Generic; using System.IO; using System.Xml; /// <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檔案,做成嵌入資源
'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 () {
try
{
console.log($("#input_baseUrl").val());
$.ajax({
type: "get",
async: true,
url: $("#input_baseUrl").val(),
dataType: "json",
success: function (data) {
var summaryDict = data.ControllerDesc;
console.log(summaryDict);
var id, controllerName, strSummary;
$("#resources_container .resource").each(function (i, item) {
id = $(item).attr("id");
if (id) {
controllerName = id.substring(9);
try {
strSummary = summaryDict[controllerName];
if (strSummary) {
$(item).children(".heading").children(".options").first().prepend('<li class="controller-summary" style="color:green;" title="' + strSummary + '">' + strSummary + '</li>');
}
} catch (e)
{
console.log(e);
}
}
});
}
});
}catch(e)
{
console.log(e);
}
},
_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();
});
第三步：修改App_Start中的SwaggerConfig.cs檔案，主要程式碼有三行
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.IncludeXmlComments(string.Format("{0}/WebApi.XML", System.AppDomain.CurrentDomain.BaseDirectory));//設定xml地址
c.CustomProvider((defaultProvider) => new SwaggerCacheProvider(defaultProvider, string.Format("{0}/WebApi.XML", System.AppDomain.CurrentDomain.BaseDirectory)));
.EnableSwaggerUi(c =>
{
c.InjectJavaScript(thisAssembly, "WebApi.Scripts.Swagger.swagger_lang.js");//漢化js
//JS資原始檔名稱空間是：檔案所在專案的名稱空間.檔案徑路.檔名
});
執行