1.Swagger UI 是什么？
Swagger UI 是一個在線的 API 文檔生成與測試工具，你可以將其集成在你的 API 項目當中。
- 支持 API 自動同步生成文檔
- 高度自定義，可以自己擴展功能
- 前后端分離時方便前端進行 API 接口測試
2.如何應用？
這里僅介紹在 DotNetCore 下如何集成 Swagger UI。
新建一個 API 項目
從 NuGet 下載 Swagger UI 包
配置 Swagger UI
安裝好 Swagger 之后，在需要生成 API 文檔的項目當中勾選 XML documentation file.
之后我們需要在 StartUp 當中配置 Swagger 相關的設置。
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new Info() { Title = "Swagger Test UI", Version = "v1" });
options.CustomSchemaIds(type => type.FullName); // 解決相同類名會報錯的問題
options.IncludeXmlComments(Path.Combine(Directory.GetCurrentDirectory(), "SwaggerUIDemo.xml")); // 標注要使用的 XML 文檔
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseStaticFiles();
app.UseSwagger();
// 在這里面可以注入
app.UseSwaggerUI(options =>
{
options.InjectOnCompleteJavaScript("/swagger/ui/zh_CN.js"); // 加載中文包
options.SwaggerEndpoint("/swagger/v1/swagger.json", "HKERP API V1");
});
app.UseMvc();
}
}
當然我們直接運行的時候會提示找不到 XML 文件，因為我們使用的是 Path.Combine(Directory.GetCurrentDirectory(), "SwaggerUIDemo.xml")，SO，我們在項目變異的時候手動 COPY 過去即可，編寫一個編譯事件。
編寫完成之后我們運行項目，訪問 swagger 的頁面就會顯示成功了：
當然這里的注釋是來自於針對 Value 控制器的注釋，Swagger 會自動掃描項目所有的控制器類，並且將其展現在 Swagger UI 當中。
DIY Swagger UI
或許到現在 Swagger 已經足夠你使用，但是如果你想針對生成的頁面進行自定義也是可以的，例如漢化文字？或者在旁邊加一個側邊欄？
這些統統都可以實現，細心的同學可能看到了在 StartUp 類的 Configure 方法當中注入了一個 JavaScript 文件，這個文件會在 Swagger UI 加載完成之后調用。那么我們就可以在這個 JS 里面操作 DOM 元素來進行自定義 UI 了。
例如漢化：
'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();
});
這里我們如果想要在 Swagger UI 上針對控制器來應用注釋的話，就需要自己實現一個 DocumentFiliter，這里我們直接繼承自 IDocumentFiliter，來實現一個自定義的 Filiter：
public class CustomDocumentFiliter : IDocumentFilter
{
public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
{
SetContorllerDescription(swaggerDoc.Extensions);
}
private void SetContorllerDescription(Dictionary<string, object> extensionsDict)
{
string _xmlPath = Path.Combine(Directory.GetCurrentDirectory(), "HKERP.Application.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;
XmlNode _summaryNode = null;
foreach (XmlNode _node in _xmlDoc.SelectNodes("//member"))
{
_type = _node.Attributes["name"].Value;
if (_type.StartsWith("T:") && !_type.Contains("T:HKERP.HKERPAppServiceBase") && !_type.Contains("T:HKERP.Net.MimeTypes.MimeTypeNames"))
{
_summaryNode = _node.SelectSingleNode("summary");
string[] _names = _type.Split('.');
string _key = _names[_names.Length - 1];
if (_key.IndexOf("AppService", _key.Length - "AppService".Length, StringComparison.Ordinal) > -1)
{
_key = _key.Substring(0, _key.Length - "AppService".Length);
}
if (_summaryNode != null && !string.IsNullOrEmpty(_summaryNode.InnerText) && !_controllerDescDict.ContainsKey(_key))
{
_controllerDescDict.TryAdd(_key, _summaryNode.InnerText.Trim());
}
}
}
extensionsDict.TryAdd("ControllerDescription", _controllerDescDict);
}
}
}
這里我們直接讀取生成的 XML 文檔，並且生成一個字典添加到 SwaggerDocument 的 Extensions 屬性當中，這樣的話，在 Swagger UI 加載的時候，調用的 JSON 接口就回附帶上我們添加的內容，這個時候只需要在 JS 文件當中獲取並且填充 UI 即可，這里有個示范：
'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;
},
setControllerSummary: function () {
var _str = $("#input_baseUrl").val();
$.ajax({
type: "get",
async: true,
url: $("#input_baseUrl").val(),
dataType: "json",
success: function (data) {
//console.log(data)
var toggleEndpointList = [];
var summaryDict = data.ControllerDescription;
var id, controllerName, strSummary;
$('body').append('<ul class="leftMenu"></ul>');
$("#resources .resource").each(function (i, item) {
id = $(item).attr("id");
if (id) {
controllerName = id.substring(9);
strSummary = summaryDict[controllerName];
if (strSummary) {
console.log($(item))
$(item).children(".heading").children("h2").children('a').text(strSummary);
$(item).children(".heading").children(".options").prepend('<li class="controller-summary" title="' + strSummary + '">' + strSummary + '</li>');
$('.leftMenu').append('<li class="menuLi" title="' + strSummary + '"><a href="" class="menuLiA">' + strSummary + '</a></li>');
toggleEndpointList.push($(item).attr('id'))
}
}
});
for (var i = 0; i < document.getElementsByClassName('menuLiA').length;i++){
var menuLiA = document.getElementsByClassName('menuLiA');
menuLiA[i].setAttribute('href', '#'+toggleEndpointList[i])
}
}
});
},
};
/* 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 () {
debugger;
window.SwaggerTranslator.translate();
window.SwaggerTranslator.setControllerSummary();
});
效果圖：
