作者：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 等的其它文章：
通過依賴注入器 "Ninject" 在 ORM （實體框架或 Dapper ）和數據庫（ SQL 服務器或Oracle 數據庫）之間進行動態選擇
使用 ASP.NET MVC、 和window Services、EF和 CRUD 實現的首個 AngularJs 應用
本文系 OneAPM 工程師編譯呈現。OneAPM 能助您輕鬆鎖定 .NET 應用性能瓶頸，通過強大的 Trace 記錄逐層分析，直至鎖定行級問題代碼。以用戶角度展示系統響應速度，以地域和瀏覽器維度統計用戶使用情況。想閱讀更多技術文章，請訪問OneAPM 官方博客。
本文轉自 OneAPM 官方博客