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

時間 2019-11-19

標籤使用 swagger swashbuckle 建立 restful web api 幫助欄目 HTML 简体版

原文原文鏈接

做者：Sreekanth Mothukuru 2016年2月18日css

本文旨在介紹如何使用經常使用的 Swagger 和 Swashbuckle 框架建立描述 Restful API 的交互界面，併爲 API 用戶提供豐富的探索、文件和操做體驗。html

源代碼: 下載 SwaggerUi_2.zipgit

###步驟github

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

建立 Asp.Net Web API項目數據庫
經過實體數據模型（.edmx）和 Scaffold API控件鏈接到 Sql Server數據庫json
整合 Swashbuckle/Swagger UI框架以描述 API 操做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 等的其它文章：