作者：Sreekanth Mothukuru
2016年2月18日
本文旨在介紹如何使用常用的 Swagger 和 Swashbuckle 框架創(chuàng)建描述 Restful API 的交互界面抬闯，并為 API 用戶提供豐富的探索假栓、文件和操作體驗(yàn)埠戳。
源代碼: 下載 SwaggerUi_2.zip
步驟
在本文中叽讳，我們將在 Asp.Net 創(chuàng)建一個(gè)簡單的 Restful API，并整合 Swashbuckle 和 Swagger UI篷角。本文分為三部分肄鸽。
創(chuàng)建 Asp.Net Web API項(xiàng)目
通過實(shí)體數(shù)據(jù)模型 （.edmx） 和 Scaffold API控件連接到 Sql Server數(shù)據(jù)庫
整合 Swashbuckle/Swagger UI框架以描述 API 操作
創(chuàng)建 Asp.Net Web API 項(xiàng)目
首先創(chuàng)建一個(gè)新的“Asp.Net Web應(yīng)用”，將其命名為“Swagger”
從模板中選擇 Web API逼龟，也就是說评凝， Visual Studio將把 MVC追葡、與Web API相關(guān)的文件夾和核心引用添加到我們的應(yīng)用中。然后奕短，點(diǎn)擊“更改權(quán)限”宜肉，選擇“無權(quán)限”后點(diǎn)擊OK。通過以上設(shè)置翎碑，我們將跳過項(xiàng)目中與賬戶相關(guān)的控件和視圖谬返。
執(zhí)行 Visual Studio 啟動(dòng)程序后，項(xiàng)目文檔和文件夾的結(jié)構(gòu)如下：
我們將在應(yīng)用 App_Start 文件夾中將 MVC 控件的路徑設(shè)置為 RouteConfig.cs 日杈，將Web API控件的路徑設(shè)置為 WebApiConfig.cs 遣铝。
注：你可以在該區(qū)域看到“幫助頁”文件夾。此文件夾將包含 Visual Studio 生成的模型莉擒、視圖酿炸、控件和其他與幫助相關(guān)的文檔，以描述Web API幫助涨冀。我們將在下文對(duì)這一問題進(jìn)行分析填硕。
如果查看 NuGet 包管理器中的“已安裝包”，你會(huì)發(fā)現(xiàn)項(xiàng)目中已經(jīng)添加了“Microsoft Asp.Net Web API 2.2 幫助頁”包鹿鳖、Razor包和核心包扁眯。
通過實(shí)體數(shù)據(jù)模型（edmx）和Scaffold API控件連接到 SQL Server數(shù)據(jù)庫
我們先通過實(shí)體數(shù)據(jù)模型將應(yīng)用連接到數(shù)據(jù)庫表。首先翅帜，創(chuàng)建新的“ADO.NET實(shí)體數(shù)據(jù)模型”項(xiàng)目姻檀，在模型文件夾中將其命名為 “SwaggerModel”。
附件為在數(shù)據(jù)庫中創(chuàng)建新表格的腳本文件涝滴。
從向?qū)е羞x擇“數(shù)據(jù)庫中的 EF Designer”绣版，并點(diǎn)擊“下一步”連接到數(shù)據(jù)庫服務(wù)器（此處即為SQL Server）周荐。
在實(shí)體數(shù)據(jù)模型向?qū)ы撁嬷校x擇連接到 Sql Server僵娃，并將連接字符串命名為“SwaggerConStr”概作，該字符串將保存在web.config文檔中。
點(diǎn)擊“下一步”默怨，選擇實(shí)體框架版本（即本文中的6.x）讯榕。點(diǎn)擊“下一步”，選擇EDMX公司表匙睹，將其保存在EDMX文檔中愚屁。
選擇表格，點(diǎn)擊“完成”按鍵痕檬，最后會(huì)生成POCO類“Company.cs”和數(shù)據(jù)庫配置指令類“SwaggerConStr” 霎槐。
現(xiàn)在已經(jīng)創(chuàng)建了實(shí)體數(shù)據(jù)模型和配置指令，那么我們可以通過Visual Studio支架特性創(chuàng)建新的API控件梦谜。但為了充分利用配置指令丘跌，在給 API 控件建立支架前，我們應(yīng)先建立應(yīng)用唁桩。即在建立支架之前闭树，刪除控件文件夾中現(xiàn)有的ValuesController.cs。
點(diǎn)擊控件文件夾荒澡，并添加“控件…”报辱，即打開帶有各種支架選項(xiàng)的“添加支架”窗口，選擇“Web API 2 Controller with actions, using Entity Framework（帶有動(dòng)作单山、使用實(shí)體框架的Web API 2控件”碍现，然后點(diǎn)擊“添加”。
在添加控件窗口中選擇模型（即本文的Company.cs）以及數(shù)據(jù)配置指令類（SwaggerConStr.cs）米奸。將新控件命名為“CompanyController.cs”昼接，并點(diǎn)擊“添加”。
為每個(gè)http 動(dòng)作（GET, PUT, POST and DELETE）操作創(chuàng)建的新控件如下：
建立和運(yùn)行應(yīng)用后躏升，可看到如下截圖辩棒。你可以在用戶界面頂端導(dǎo)航中看到“API”鏈接，點(diǎn)擊后進(jìn)入“Asp.Net API幫助頁”頁面膨疏。幫助主頁如下所示一睁。
注：為了檢查API，應(yīng)在url中添加“/api/company”佃却，并在瀏覽器中提交者吁。
點(diǎn)擊任意操作鏈接后將顯示更多詳情，如帶有URI饲帅、本體參數(shù)的“請(qǐng)求”信息复凳、“響應(yīng)”類型瘤泪、json或xml等格式。下圖為GET方法截圖：
雖然Visual Studio團(tuán)隊(duì)花費(fèi)了很大精力為這項(xiàng)服務(wù)的消費(fèi)者展示W(wǎng)eb API幫助育八，但這項(xiàng)服務(wù)的薄弱點(diǎn)是用戶界面過于基礎(chǔ)对途，而且我們無法使用動(dòng)作方法。這正是有必要使用Swagger UI & Swashbuckle的原因髓棋。
整合 Swashbuckle/Swagger UI实檀，以描繪API操作
由Swagger網(wǎng)站可知，Swagger是展示RESTful API的簡單而強(qiáng)大的方法按声，它為此API提供了強(qiáng)大的接口膳犹。
由Swashbuckle GitHub可知，Swashbuckle可將Swagger無縫添加到WebApi中签则！將ApiExplorer與Swagger/swagge-ui 合并可以給 API 用戶帶來豐富的探索须床、文件和操作體驗(yàn)。除Swagger生成器外渐裂，Swashbuckle還包含嵌入式版本的swagger-ui豺旬。
將Swashbuckle添加到 Web API中
點(diǎn)擊進(jìn)入“ Manage NuGet Packages…（管理NuGet包）”，并在線搜索“Swashbuckle”芯义。在列表中選擇Richard Morris創(chuàng)建的5.2.2版 “Swashbuckle - Swagger for Web API”哈垢，點(diǎn)擊安裝。
這一操作會(huì)將引用添加到“Swashbuckle - Swagger for Web API”與“Swashbuckle.Core - Swagger for Web API”中扛拨。且后者會(huì)在經(jīng)過依賴檢查后添加到我們的項(xiàng)目中。在packages.config中也是如此举塔。
<package id="Swashbuckle" version="5.2.2" targetFramework="net45" />
<package id="Swashbuckle.Core" version="5.2.2" targetFramework="net45" />
成功安裝后绑警，我們可以在App_Start文件夾中看到一個(gè)新的“SwaggerConfig.cs”配置文檔，所有Swagger相關(guān)配置都會(huì)在此進(jìn)行設(shè)置央渣。
為了能直接鏈接到Swagger API 接口计盒，應(yīng)將下列所有動(dòng)作鏈接到“_Layout.cshtml”頁面的頂部導(dǎo)航欄。
<li>@Html.ActionLink("Swagger Help", "", "Swagger", new { area = "" }, null)</li>
現(xiàn)在芽丹，建立并運(yùn)行應(yīng)用北启。點(diǎn)擊頂部導(dǎo)航的“Swagger Help”后進(jìn)入Swagger用戶界面。點(diǎn)擊列表操作（List Operations）拔第，查看所有交互指令操作及相應(yīng)的動(dòng)詞咕村。
點(diǎn)擊操作后會(huì)顯示響應(yīng)類別。點(diǎn)擊“Try it out（試試看）!”按鍵后可顯示請(qǐng)求URL蚊俺、響應(yīng)體懈涛、響應(yīng)代碼和響應(yīng)頭等細(xì)節(jié)。
GET操作:
POST操作細(xì)節(jié):
刪除操作細(xì)節(jié):
通過Id進(jìn)行GET操作的細(xì)節(jié):
PUT操作細(xì)節(jié):
將XML注解包含在幫助文件中
點(diǎn)擊進(jìn)入項(xiàng)目屬性泳猬，在建立標(biāo)簽下的輸出區(qū)勾選“XML documentation file（XML文檔文件）:”后批钠，即可在保存文檔的二進(jìn)制文件夾中看到 XML 路徑宇植。
接著打開Swagger配置文檔，并添加 “IncludeXmlComments”語句埋心，該語句可將路徑從二進(jìn)制文件夾返回至 XML 文檔指郁。
private static string GetXmlCommentsPath()
{
return String.Format(@"{0}\bin\SwaggerUi.XML", System.AppDomain.CurrentDomain.BaseDirectory);
}
在SwaggerConfig.cs Register靜態(tài)方法中啟用全局配置的方式如下：
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "SwaggerUi");
c.IncludeXmlComments(GetXmlCommentsPath());
})
.EnableSwaggerUi(c =>
{
});
}
用以下注解編輯控件GET方法，可檢查 XML 注解是否運(yùn)行：
運(yùn)行應(yīng)用拷呆，并通過頂部導(dǎo)航欄導(dǎo)航到Swagger幫助頁面坡氯。隨后可看到添加到Swagger幫助頁面的XML注解。
用自定義CSS定制Swagger用戶界面
Swashbuckle文件規(guī)定開發(fā)者可用預(yù)定義的 “InjectStylesheet” 方法洋腮，將自定義 .css文件作為嵌入式資源注入箫柳。我們需要將文件的“Logical Name（邏輯名稱）”作為第二個(gè)參數(shù)，“media=screen”作為第三個(gè)可選參數(shù)啥供，當(dāng)前裝配作為第一個(gè)參數(shù)悯恍。
在內(nèi)容文件夾中創(chuàng)建一個(gè)新的名為 “myStyle.css”的css文件，并通過添加以下樣式將標(biāo)題默認(rèn)背景色從綠色改成藍(lán)色伙狐。
.swagger-section #header {
background-color: #0000ff;
padding: 14px;
}
右鍵點(diǎn)擊文檔涮毫，選擇屬性，并將其Build操作設(shè)置為“嵌入式資源”
現(xiàn)在贷屎，將以下代碼添加到 Swagger 配置設(shè)置中罢防，以啟動(dòng)用戶界面：
c.InjectStylesheet(thisAssembly, "SwaggerUi.Content.myStyle.css");
注:樣式表單文件的“邏輯名稱”。
現(xiàn)在運(yùn)行應(yīng)用唉侄，觀察變化咒吐。
用自定義 JavaScript 定制 Swagger UI:
Swashbuckle 文件規(guī)定開發(fā)者可用預(yù)定義的InjectJavaScript” 方法，將自定義的JavaScript 文件作為嵌入式資源注入属划。我們要將文檔的 “**Logical Name **”作為第二參數(shù)恬叹，將當(dāng)前裝配作為第一參數(shù)。
在腳本文件夾中創(chuàng)建新的 JavaScript 文件 “myScript.js” 同眯，并添加以下基本腳本绽昼，這樣文件加載時(shí)可顯示自定義的告警消息。
$(document).ready(function () {
alert("Hello from custom JavaScript file.");
});
右鍵點(diǎn)擊文檔须蜗，選擇屬性硅确，將其Build操作設(shè)置為“嵌入式資源”
現(xiàn)在將以下代碼添加到 Swagger 配置設(shè)置中，以啟動(dòng)用戶界面：
c.InjectJavaScript(thisAssembly, "SwaggerUi.Scripts.myScript.js");
注: Java 描述文件的“邏輯名稱”明肮。
運(yùn)行應(yīng)用菱农，以查看告警消息：
注: 我們可以在與API幫助交互之前，通過 “InjectJavaScript” 特性添加自己的用戶界面和行為晤愧。請(qǐng)參考 Steve Michelotti 的文章---"在使用Swashbuckle的Swagger UI定制認(rèn)證標(biāo)頭"大莫。
最后， SwaggerConfig Register 方法文件如下所示：
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "SwaggerUi");
c.IncludeXmlComments(GetXmlCommentsPath());
})
.EnableSwaggerUi(c =>
{
c.InjectStylesheet(thisAssembly, "SwaggerUi.Content.myStyle.css");
c.InjectJavaScript(thisAssembly, "SwaggerUi.Scripts.myScript.js");
});
}
還有其它的定制方法官份，筆者今后將更新本文只厘。
查看筆者關(guān)于 Asp.Net MVC 烙丛、 Web API 、 Angular 等的其它文章：
使用 FooTable 創(chuàng)建響應(yīng)式 HTML 表并使用 Handlebars.Js 應(yīng)用客戶端綁定
使用 ASP.NET MVC羔味、
window Services河咽、EF和 CRUD 實(shí)現(xiàn)的首個(gè) AngularJs 應(yīng)用
本文系 OneAPM 工程師編譯呈現(xiàn)。OneAPM 能助您輕松鎖定 .NET 應(yīng)用性能瓶頸赋元，通過強(qiáng)大的 Trace 記錄逐層分析忘蟹，直至鎖定行級(jí)問題代碼。以用戶角度展示系統(tǒng)響應(yīng)速度搁凸，以地域和瀏覽器維度統(tǒng)計(jì)用戶使用情況媚值。想閱讀更多技術(shù)文章，請(qǐng)?jiān)L問 OneAPM 官方博客护糖。
本文轉(zhuǎn)自 OneAPM 官方博客
