使用 Swagger UI 與 Swashbuckle 建立 RESTful Web API 幫助檔案

OneAPM官方技術部落格發表於2016-04-14
SwaggerUIRESTWebAPI

作者：Sreekanth Mothukuru 2016年2月18日

本文旨在介紹如何使用常用的 Swagger 和 Swashbuckle 框架建立描述 Restful API 的互動介面，併為 API 使用者提供豐富的探索、檔案和操作體驗。

原始碼: 下載 SwaggerUi_2.zip

步驟

在本文中，我們將在 Asp.Net 建立一個簡單的 Restful API，並整合 Swashbuckle 和 Swagger UI。本文分為三部分。

  1. 建立 Asp.Net Web API專案

  2. 通過實體資料模型 （.edmx） 和 Scaffold API控制元件連線到 Sql Server資料庫

  3. 整合 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 官方部落格。

原文地址：http://www.codeproject.com/Articles/1078249/RESTful-Web-API-Help-Documentation-using-Swagger-U#_articleTop

本文轉自 OneAPM 官方部落格

相關文章