Swagger for Web API Document - Part Ⅱ

相信經過上一篇文章的介紹,
各位讀者對於在 Asp.Net Web API 中整合 Swagger 的應用已經有了一定的基礎,
（回顧： Swagger for Web API Document - Part Ⅰ ）
接下來我們將更進一步地介紹如何讓 Swagger 支援 API Key / Token, 以及在 UI 上呈現 API 的 Request / Response Examples, 透過這些進階整合, 提供使用者更友善的操作體驗：

▎讓 API 支援 API Key / Token

以往我們在呼叫 3rd 提供的 API 時, 需在 Header 中夾帶一組 API Key 或 Token 來提供對方驗證, 以下我們將介紹, 如何透過一些設定, 讓 Swagger UI 也能預設在每一段的 API Request Header 中預設加入一組  API Key 或 Token：

1. 
   
   1. 打開 Swagger 的設定檔 SwaggerConfig.cs 後, 於 GlobalConfiguration.Configuration.EnableSwaggerUi 設定中, 加入 EnableApiKeySupport 設定：
      
      [code language="cpp"]
      
      GlobalConfiguration.Configuration.EnableApiKeySupport(
      　c => {
      　　// 預設將 APIKey 帶入 Header 送出 Request
      　　c.EnableApiKeySupport("APIKey", "header");
      });
      
      [/code]
      
      
   2. 於 Swagger UI 右上方「api_key」輸入框中輸入 API Key 或 Token 後點選【Explore】刷新下方 API Operations：
      
   3. 最後, 只要檢查 API 發送 Request 是否正確夾帶 API Key 或 Token 進指定的 Header 參數即完成：
      

▎加入 API's Request & Response Examples

為了讓 Swagger UI 在使用上更加方便, 通常我們會提供一些 Default / Sample Value 給予使用者在發送 API Request 測試用, 或是在 API Services 尚未開發完成前, 需預先提供 API 接口及其 Response Example 給予對方的 RD 預先開發參考用, 這時我們就可以透過 Swagger 服務套件「Swashbuckle.Examples」來達成這樣的效果：

▎擴充套件安裝

透過 Visual Studio 管理 Nuget 套件搜尋「Swashbuckle.Examples」並安裝：


或透過 Visual Studio 的套件管理器主控台下指令：

[code language="bash"]

PM> Install-Package Swashbuckle.Examples -Version 3.10.0

[/code]

▎環境設定

在 Swagger 設定檔的 GlobalConfiguration.Configuration.EnableSwagger 設定中, 加入初始 ExamplesOperationFilter 作業：

[code language="cpp"]

GlobalConfiguration.Configuration.EnableSwagger(
c => {
　// 援 Response 與 Request 客製化 Example Value
　c.OperationFilter<ExamplesOperationFilter>();
});

[/code]

▎套用 Request Examples 至 API

首先, 我們先建立一個 Model 類別來乘載資料（ProductModel.cs）：

[code language="cpp"]

/// <summary>
/// 產品資料模型
/// </summary>
public class ProductModel
{
　/// <summary>
　/// 編輯模型
　/// </summary>
　public class EditView
　{
　　/// <summary>
　　/// 名稱
　　/// </summary>
　　[Required]
　　public string name { get; set; }

　　/// <summary>
　　/// 單價
　　/// </summary>
　　[Required]
　　public decimal? price { get; set; }

　　/// <summary>
　　/// 數量
　　/// </summary>
　　[Required]
　　public int? quantity { get; set; }

　　/// <summary>
　　/// 描述
　　/// </summary>
　　public string desc { get; set; }
　}
}

[/code]

再來需建立一個 implement IExamplesProvider 的 Examples 類別（ProductEditRequestExample.cs）：

[code language="cpp"]

/// <summary>
/// 產品編輯 Request 範例
/// </summary>
public class ProductEditRequestExample : IExamplesProvider
{
　/// <summary>
　/// 取得範例
　/// </summary>
　/// <returns></returns>
　public object GetExamples()
　{
　　return new ProductModel.EditView()
　　{
　　　name = "鑽石鍋子",
　　　price = 136,
　　　quantity = 100,
　　　desc = "Bring Bring 的鍋子"
　　};
　}
}

[/code]

並於指定的 Action 掛上 Swashbuckle.Examples 命名空間中的 [SwaggerRequestExample] Attribute 設定：


最後, 讓我們看看結果吧：

▎套用 Response Examples 至 API

建立一個 implement IExamplesProvider 的 Examples 類別（ProductQueryResponseExample.cs）：

[code language="cpp"]

/// <summary>
/// 產品查詢 Response 範例
/// </summary>
public class ProductQueryResponseExample : IExamplesProvider
{
　/// <summary>
　/// 取得範例
　/// </summary>
　/// <returns></returns>
　public object GetExamples()
　{
　　return new List<ProductModel.EditView>()
　　{
　　　new ProductModel.EditView() { name = "鑽石鍋子", price = 136, quantity = 100, desc = "Bring Bring 的鍋子" },
　　　new ProductModel.EditView() { name = "白金鍋子", price = 100, quantity = 583, desc = "Bring 的鍋子" }
　　};
　}
}

[/code]

再來, 搭配 [SwaggerResponse] Annotation, 加上 Swashbuckle.Examples 命名空間中的 [SwaggerResponseExample] Attribute 設定：


最後, 讓我們看看結果吧：

▎結語

透過 Swagger 這個工具, 在 Asp.Net 的專案中, 搭配 Swashbuckle & Swashbuckle.Examples 套件, 即可簡單地實作出 Online API Document, 也實現「程式即文件」的快速開發精神。除此之外, Swagger 也有利於開發人員即時測試使用, 並且讓非開發人員在使用上更加友善, 相互搭配我們原先常用來測試 API 的 Postman 工具, 使得我們在 API 的測試與使用上更加全面及便利。