Swagger for Web API Document – Part Ⅰ

以往,
我們在開發 API 的過程中,
通常需要提供一份接口文件給其他團隊瀏覽或測試,
而這份文件往往都需要花費大量時間與成本在專案開發中、後期來完成它,
最近剛好小編也正著手開發一個新的 Web API 專案,
有預先針對 API Document 的實作進行 Survey,
希望能在開發 API 的同時即能產出一份「符合 RESTful API 規範的線上文件」,

經過一番審慎評估後,
在 API BlueprintSwagger 間選擇了 Swagger 作為該專案的 API Document 工具,
其原因在於 Swagger 的「程式碼與文件兩者並存」的開發方式深深吸引了我,
再進一步研究過 微軟官方 建議的 Swagger 服務套件「Swashbuckle」後,
使我更能感受到以 XML 文件註解的方式搭配 Annotation 的定義來實現「程式即文件」的快速開發精隨,
※ 註:習慣 Markdown 語法, 且需提供文件下載(如:Html)即建議採用 API Blueprint

接下來將簡單介紹如何安裝及使用「Swashbuckle」套件來完成 Swagger API Document 的建置!

套件安裝

首先, 透過 Visual Studio 管理 Nuget 套件搜尋「Swashbuckle」並安裝:

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

 
PM> Install-Package Swashbuckle -Version 5.6.0 

環境設定

安裝完 Nuget  Package 後, 會發現 App_Start 目錄下會多一個 「SwaggerConfig.cs」檔案, 為了提供 Swagger 正確「產出」及「讀取」相關 API 接口資訊(XML Document), 需要進行以下 4 個操作步驟:

  1. 於 GlobalConfiguration.Configuration.EnableSwagger 設定中, 加入 IncludeXmlComments 設定:
     
    
    GlobalConfiguration.Configuration.EnableSwagger(
     c => {
      // 取得 Swagger XML 產出的路徑(如設定已存在請反註解) 
      c.IncludeXmlComments(GetXmlCommentsPath()); 
    });
    
    
  2. 並在設定檔下方實作 GetXmlCommentsPath 的方法:
     
    
    /// <summary>
    /// 取得 Swagger XML 產出的路徑
    /// </summary>
    internal static string GetXmlCommentsPath()
    {
     return System.String.Format(@"{0}\App_Data\SwaggerXmlDoc.xml", System.AppDomain.CurrentDomain.BaseDirectory);
    }
    
    
  3. 在專案上方點選右鍵, 打開屬性設定, 在【建置】頁籤中將輸出區塊的【XML 文件檔案】打勾, 並填入 Swagger XML 產出的路徑(App_Data/SwaggerXmlDoc.xml), 即完成設定:
  4. 完成上述設定後, 將專案啟動執行, 並於網址根目錄後方加上 Swagger 即可看到 Swagger Online API Document(如:http://localhost:59820/Swagger):

建立 API 功能

首先, 我們先將 Demo Code 提供給大家參考與練習:


/// <summary>
/// 產品 API 列表
/// </summary>
[RoutePrefix("api/Products")]
[SwaggerResponse(HttpStatusCode.OK, Description = "要求成功,回應要求結果。")]
[SwaggerResponse(HttpStatusCode.NoContent, Description = "成功處理要求,無回應任何結果。")]
[SwaggerResponse(HttpStatusCode.Unauthorized, Description = "驗證失敗,請確認 API Key 有效性。")]
[SwaggerResponse(HttpStatusCode.BadRequest, Description = "請確認 Uri 及相關 Parameters 是否正確。")]
public class ProductsController : ApiController
{
 /// <summary>
 /// 取得所有產品資料
 /// </summary>
 /// <param name="name">名稱</param>
 /// <param name="desc">描述</param>
 /// <remarks>可使用產品「名稱」與「描述」關鍵字查詢產品資料</remarks>
 /// <returns>所有產品資料</returns>
 [HttpGet]
 public HttpResponseMessage Get(string name, string desc = null)
 {
  return Request.CreateResponse(HttpStatusCode.OK);
 }

 /// <summary>
 /// 取得指定產品資料
 /// </summary>
 /// <param name="id">指定產品編號</param>
 /// <returns>指定產品資料</returns>
 [HttpGet]
 [SwaggerResponse(HttpStatusCode.OK, Description = "要求成功,回應要求結果。(客製)", Type = typeof(ProductModel.EditView))]
 public HttpResponseMessage Get(int id)
 {
  return Request.CreateResponse(HttpStatusCode.OK, new ProductModel.EditView());
 }

 /// <summary>
 /// 新增產品
 /// </summary>
 /// <param name="model">產品編輯模型</param>
 /// <returns>新增產品結果</returns>
 [HttpPost]
 public HttpResponseMessage Post([FromBody]ProductModel.EditView model)
 {
  int insertedId = new Random().Next(int.MinValue, int.MaxValue);
  return Request.CreateResponse(HttpStatusCode.OK, new { id = insertedId });
 }

 /// <summary>
 /// 修改產品
 /// </summary>
 /// <param name="id">指定產品編號</param>
 /// <param name="model">產品編輯模型</param>
 /// <returns>修改產品結果</returns>
 [HttpPut]
 public HttpResponseMessage Put(int id, [FromBody]ProductModel.EditView model)
 {
  return Request.CreateResponse(HttpStatusCode.OK);
 }

 /// <summary>
 /// 刪除產品
 /// </summary>
 /// <param name="id">指定產品編號</param>
 /// <returns>新增產品結果</returns>
 [HttpDelete]
 public HttpResponseMessage Delete(int id)
 {
  return Request.CreateResponse(HttpStatusCode.OK);
 }

 /// <summary>
 /// 取得產品進貨資訊
 /// </summary>
 /// <param name="id">指定產品編號</param>
 /// <returns>產品進貨資訊</returns>
 [HttpGet]
 [Route("{id}/Purchase")]
 public HttpResponseMessage GetPurchaseInfo(int id)
 {
  return Request.CreateResponse(HttpStatusCode.OK);
 }
}

以下, 我們將以代碼與畫面對應的方式來逐步說明程式於 Swagger UI 上的實現:

關於 API 的描述與參數說明

在 Controller / Action 上填寫 XML Annotation 內容, 在 Swagger UI 即可呈現出對應的內容, 關於參數的部分, Swagger 也可完整呈現必填或可選的提示(也包含 Model [Required] Annotation 的支援):

對應 API 各種 HTTP Status 的 Response

可以在 Controller / Action 加上 Swagger Annotations 命名空間中的 [SwaggerResponse] Annotation 來定義每個 HTTP Status 對應的 Response 訊息。

當在 Action 上套用 [SwaggerResponse] Annotation 時, 有明確給予 Response Type 的資訊, 在 Swagger UI 上即會呈現完整的 Response Class 資訊(Model Schema  & Example Value):

支援 ASP.NET Routing 機制

依循 REST Resource Naming Guide, 專案如果需要支援 Nested Resources API(如:GET /api/collectionA/{id}/collectionB/{id}), 我們可透過 ASP.NET Routing 的機制, 搭配 [RoutePrefix] 與 [Route] Attributes 來實現, 而 Swagger UI 也無痛支援  ASP.NET Routing 的機制:

小結

根據上述說明操作, 即可完成基本的 Swagger API Document 的建置, 在下一篇文章中, 我們將進一步地介紹如何在 Swagger UI 介面中輸入並支援「API Key & Token」以及在畫面上提供「API’s Request & Response Examples」來提升使用者體驗。

廢話不多說, 一起前往 Swagger for Web API Document – Part Ⅱ 吧!

 

作者: Steven Tsai

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

發表迴響