作者：Sreekanth Mothukuru
2016年2月18日
本文旨在介紹如何使用常用的 Swagger 和 Swashbuckle 框架創建描述 Restful API 的交互界面，并為 API 用戶提供豐富的探索、文件和操作體驗。
源代碼: 下載 SwaggerUi_2.zip
步驟
在本文中，我們將在 Asp.Net 創建一個簡單的 Restful API，并整合 Swashbuckle 和 Swagger UI。本文分為三部分。
創建 Asp.Net Web API項目
通過實體數據模型 （.edmx） 和 Scaffold API控件連接到 Sql Server數據庫
整合 Swashbuckle/Swagger UI框架以描述 API 操作
創建 Asp.Net Web API 項目
首先創建一個新的“Asp.Net Web應用”，將其命名為“Swagger”
從模板中選擇 Web API，也就是說， Visual Studio將把 MVC、與Web API相關的文件夾和核心引用添加到我們的應用中。然后，點擊“更改權限”，選擇“無權限”后點擊OK。通過以上設置，我們將跳過項目中與賬戶相關的控件和視圖。
執行 Visual Studio 啟動程序后，項目文檔和文件夾的結構如下：
我們將在應用 App_Start 文件夾中將 MVC 控件的路徑設置為 RouteConfig.cs ，將Web API控件的路徑設置為 WebApiConfig.cs 。
注：你可以在該區域看到“幫助頁”文件夾。此文件夾將包含 Visual Studio 生成的模型、視圖、控件和其他與幫助相關的文檔，以描述Web API幫助。我們將在下文對這一問題進行分析。
如果查看 NuGet 包管理器中的“已安裝包”，你會發現項目中已經添加了“Microsoft Asp.Net Web API 2.2 幫助頁”包、Razor包和核心包。
通過實體數據模型（edmx）和Scaffold API控件連接到 SQL Server數據庫
我們先通過實體數據模型將應用連接到數據庫表。首先，創建新的“ADO.NET實體數據模型”項目，在模型文件夾中將其命名為 “SwaggerModel”。
附件為在數據庫中創建新表格的腳本文件。
從向導中選擇“數據庫中的 EF Designer”，并點擊“下一步”連接到數據庫服務器（此處即為SQL Server）。
在實體數據模型向導頁面中，選擇連接到 Sql Server，并將連接字符串命名為“SwaggerConStr”，該字符串將保存在web.config文檔中。
點擊“下一步”，選擇實體框架版本（即本文中的6.x）。點擊“下一步”，選擇EDMX公司表，將其保存在EDMX文檔中。
選擇表格，點擊“完成”按鍵，最后會生成POCO類“Company.cs”和數據庫配置指令類“SwaggerConStr” 。
現在已經創建了實體數據模型和配置指令，那么我們可以通過Visual Studio支架特性創建新的API控件。但為了充分利用配置指令，在給 API 控件建立支架前，我們應先建立應用。即在建立支架之前，刪除控件文件夾中現有的ValuesController.cs。
點擊控件文件夾，并添加“控件…”，即打開帶有各種支架選項的“添加支架”窗口，選擇“Web API 2 Controller with actions, using Entity Framework（帶有動作、使用實體框架的Web API 2控件”，然后點擊“添加”。
在添加控件窗口中選擇模型（即本文的Company.cs）以及數據配置指令類（SwaggerConStr.cs）。將新控件命名為“CompanyController.cs”，并點擊“添加”。
為每個http 動作（GET, PUT, POST and DELETE）操作創建的新控件如下：
建立和運行應用后，可看到如下截圖。你可以在用戶界面頂端導航中看到“API”鏈接，點擊后進入“Asp.Net API幫助頁”頁面。幫助主頁如下所示。
注：為了檢查API，應在url中添加“/api/company”，并在瀏覽器中提交。
點擊任意操作鏈接后將顯示更多詳情，如帶有URI、本體參數的“請求”信息、“響應”類型、json或xml等格式。下圖為GET方法截圖：
雖然Visual Studio團隊花費了很大精力為這項服務的消費者展示Web API幫助，但這項服務的薄弱點是用戶界面過于基礎，而且我們無法使用動作方法。這正是有必要使用Swagger UI & Swashbuckle的原因。
整合 Swashbuckle/Swagger UI，以描繪API操作
由Swagger網站可知，Swagger是展示RESTful API的簡單而強大的方法，它為此API提供了強大的接口。
由Swashbuckle GitHub可知，Swashbuckle可將Swagger無縫添加到WebApi中！將ApiExplorer與Swagger/swagge-ui 合并可以給 API 用戶帶來豐富的探索、文件和操作體驗。除Swagger生成器外，Swashbuckle還包含嵌入式版本的swagger-ui。
將Swashbuckle添加到 Web API中
點擊進入“ Manage NuGet Packages…（管理NuGet包）”，并在線搜索“Swashbuckle”。在列表中選擇Richard Morris創建的5.2.2版 “Swashbuckle - Swagger for Web API”，點擊安裝。
這一操作會將引用添加到“Swashbuckle - Swagger for Web API”與“Swashbuckle.Core - Swagger for Web API”中。且后者會在經過依賴檢查后添加到我們的項目中。在packages.config中也是如此。
<package id="Swashbuckle" version="5.2.2" targetFramework="net45" />
<package id="Swashbuckle.Core" version="5.2.2" targetFramework="net45" />
成功安裝后，我們可以在App_Start文件夾中看到一個新的“SwaggerConfig.cs”配置文檔，所有Swagger相關配置都會在此進行設置。
為了能直接鏈接到Swagger API 接口，應將下列所有動作鏈接到“_Layout.cshtml”頁面的頂部導航欄。
<li>@Html.ActionLink("Swagger Help", "", "Swagger", new { area = "" }, null)</li>
現在，建立并運行應用。點擊頂部導航的“Swagger Help”后進入Swagger用戶界面。點擊列表操作（List Operations），查看所有交互指令操作及相應的動詞。
點擊操作后會顯示響應類別。點擊“Try it out（試試看）!”按鍵后可顯示請求URL、響應體、響應代碼和響應頭等細節。
GET操作:
POST操作細節:
刪除操作細節:
通過Id進行GET操作的細節:
PUT操作細節:
將XML注解包含在幫助文件中
點擊進入項目屬性，在建立標簽下的輸出區勾選“XML documentation file（XML文檔文件）:”后，即可在保存文檔的二進制文件夾中看到 XML 路徑。
接著打開Swagger配置文檔，并添加 “IncludeXmlComments”語句，該語句可將路徑從二進制文件夾返回至 XML 文檔。
private static string GetXmlCommentsPath()
{
return String.Format(@"{0}\bin\SwaggerUi.XML", System.AppDomain.CurrentDomain.BaseDirectory);
}
在SwaggerConfig.cs Register靜態方法中啟用全局配置的方式如下：
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "SwaggerUi");
c.IncludeXmlComments(GetXmlCommentsPath());
})
.EnableSwaggerUi(c =>
{
});
}
用以下注解編輯控件GET方法，可檢查 XML 注解是否運行：
運行應用，并通過頂部導航欄導航到Swagger幫助頁面。隨后可看到添加到Swagger幫助頁面的XML注解。
用自定義CSS定制Swagger用戶界面
Swashbuckle文件規定開發者可用預定義的 “InjectStylesheet” 方法，將自定義 .css文件作為嵌入式資源注入。我們需要將文件的“Logical Name（邏輯名稱）”作為第二個參數，“media=screen”作為第三個可選參數，當前裝配作為第一個參數。
在內容文件夾中創建一個新的名為 “myStyle.css”的css文件，并通過添加以下樣式將標題默認背景色從綠色改成藍色。
.swagger-section #header {
background-color: #0000ff;
padding: 14px;
}
右鍵點擊文檔，選擇屬性，并將其Build操作設置為“嵌入式資源”
現在，將以下代碼添加到 Swagger 配置設置中，以啟動用戶界面：
c.InjectStylesheet(thisAssembly, "SwaggerUi.Content.myStyle.css");
注:樣式表單文件的“邏輯名稱”。
現在運行應用，觀察變化。
用自定義 JavaScript 定制 Swagger UI:
Swashbuckle 文件規定開發者可用預定義的InjectJavaScript” 方法，將自定義的JavaScript 文件作為嵌入式資源注入。我們要將文檔的 “**Logical Name **”作為第二參數，將當前裝配作為第一參數。
在腳本文件夾中創建新的 JavaScript 文件 “myScript.js” ，并添加以下基本腳本，這樣文件加載時可顯示自定義的告警消息。
$(document).ready(function () {
alert("Hello from custom JavaScript file.");
});
右鍵點擊文檔，選擇屬性，將其Build操作設置為“嵌入式資源”
現在將以下代碼添加到 Swagger 配置設置中，以啟動用戶界面：
c.InjectJavaScript(thisAssembly, "SwaggerUi.Scripts.myScript.js");
注: Java 描述文件的“邏輯名稱”。
運行應用，以查看告警消息：
注: 我們可以在與API幫助交互之前，通過 “InjectJavaScript” 特性添加自己的用戶界面和行為。請參考 Steve Michelotti 的文章---"在使用Swashbuckle的Swagger UI定制認證標頭"。
最后， 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");
});
}
還有其它的定制方法，筆者今后將更新本文。
查看筆者關于 Asp.Net MVC 、 Web API 、 Angular 等的其它文章：
本文系 OneAPM 工程師編譯呈現。OneAPM 能助您輕松鎖定 .NET 應用性能瓶頸，通過強大的 Trace 記錄逐層分析，直至鎖定行級問題代碼。以用戶角度展示系統響應速度，以地域和瀏覽器維度統計用戶使用情況。想閱讀更多技術文章，請訪問 OneAPM 官方博客。
本文轉自 OneAPM 官方博客
