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. 打開 Swagger 的設定檔 SwaggerConfig.cs 後, 於 GlobalConfiguration.Configuration.EnableSwaggerUi 設定中, 加入 EnableApiKeySupport 設定:
       
      
      GlobalConfiguration.Configuration.EnableApiKeySupport(
       c => {
        // 預設將 APIKey 帶入 Header 送出 Request
        c.EnableApiKeySupport("APIKey", "header"); 
      });
      
      
    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 的套件管理器主控台下指令:

 

PM> Install-Package Swashbuckle.Examples -Version 3.10.0 

環境設定

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

 

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

套用 Request Examples 至 API

首先, 我們先建立一個 Model 類別來乘載資料(ProductModel.cs):

 

/// <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; }
 }
}

再來需建立一個 implement IExamplesProvider 的 Examples 類別(ProductEditRequestExample.cs):

 

/// <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 的鍋子"
  };
 }
}

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

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

套用 Response Examples 至 API

建立一個 implement IExamplesProvider 的 Examples 類別(ProductQueryResponseExample.cs):


/// <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 的鍋子" }
  };
 }
}

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

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

結語

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

作者: Steven Tsai

大家好, 我是 Steven Tsai, 目前在叡揚資訊技術開發中心(TDS/DC)擔任程式分析師(PA), 在公司主要負責支援其他部門的專案開發, 並樂於協助及解決新人與其他同仁在開發技術上所遇到的瓶頸. 往後也會陸續將學習心得與開發經驗整理並記錄到 Blog 上, 歡迎志同道合的朋友們一起加入討論與研究. Steven's Tech Notepad

發表迴響