[WEB API] 使用 Swagger 自動產生 WebAPI 技術文件

Swagger 是什麼
以下是 Swagger 官網說明
“ Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API “ 
Swagger 是一個可以將你的 API 接口變成可視化的服務，透過 Swagger 提供的工具能動態產生HTML、CSS、Javascript 網頁版的文件，相對應的接口清單，接口的使用方式 (HTTP Method)、API 簽章(參數名稱) 以及直接在網頁上進行接口測試的動作，驗證 API 接口服務是否正常

為什麼要用 Swagger
好的開發文件可以讓 User 清楚知道如何使用 API 接口，但大部分的工程師對於寫文件這件事都沒什麼好感，但偏偏在開發時又希望有清楚的文件 (好難搞...)，以下整理個人覺得帶來的好處

• 建立文件 : 專案有寫出來的 Code 等同於技術文件，減少額外寫文件及維護文件的成本
• 方便溝通 : 讓你的服務端使用者像是前端、QA、Support 同仁清楚的知道接口相關資訊
• 方便測試 : 使用線上文件進行測試，透過網頁立即知道 API 返回的結果，節省溝通時間提升效率

如何使用
要在 WebAPI 專案使用 Swagger 很簡單，只需要透過 Nuget 下載安裝 Swagger 相關 package即可，以下整理基本安裝過程與步驟

安裝 Swashbuckle

Step 1. 在 Web API 專案按右鍵 > Manage Nuget Package

Step 2. 點選 Browser > 搜尋框輸入 Swashbuckle > 下載

Step 3. 安裝 Swashbuckle 過程中會一併安裝 Swashbuckle.Core 套件

Step 4. 安裝完畢會提示 Web.Config 需要 Reload，選擇  Yes to all

Step 5. 如何確定有安裝成功 ? 可以到專案點開 reference > 確認有 Swashbuckle.Core 就代表安裝完成啦

設定專案 XML 註解

安裝完畢後接下來設定專案輸出的 XML 註解，註解來源是從 Class 上方按下三個反斜線 "///" 區塊內容擷取的，專案預設不會開啟需要手動設定輸出註解位置，Swagger 在自動產生技術文件需要此資訊
Step 1. 在 Web API 專案按右鍵 > 選擇 Properties
Step 2. Tab 選擇 Build > 選取 XML documentation file 路徑輸入 XML 要產生的路徑位置

Step 3. 接著在 Controller 方法加上註解，按下 "///" 會自動產生 Comment

設定完後每次專案建置完會在 App_Data folder 產生 XML 檔案，但 Visual Studio 在 compiler 同時也會檢查專案中哪些地方尚未加上 XML Comment (Compiler warning CS1591)，會在建置完後提示如下圖片顯示

Step 4. 覺得不想看到沒關係把它關掉就好 : 選擇 Build > Errors and Warnings > Suppress warnings 輸入 1591，透過設定不再提示 missing xml Warnings 訊息資訊

設定 SwaggerConfig

安裝完 Swagger package，產生完專案 XML Comment，下一步就是告訴 Swagger 產生線上文件的位置，Swagger 安裝完後會在專案 App_Start 資料夾下新增 SwaggerConfig.cs 檔案，開啟檔案做以下調整
Step 1. 在 SwaggerConfig.cs 搜尋 IncludeXmlComments > 將此行反註解

Step 2. 註解拿掉後會發現缺少 GetXmlCommentsPath 方法，這邊就是定義剛專案檔設定的 XML Document 位置，因此直接加上此方法與 Code 如下

private static  string GetXmlCommentsPath()
{
    return String.Format(
        @"{0}\App_Data\XmlDocument.xml",
        AppDomain.CurrentDomain.BaseDirectory);
}

使用 swagger 

完成上述步驟你衷心盼望的 WEB API 文件就完成了，在 Application 網址後加上 /swagger，就可以看到swagger 幫你產生的 API 線上文件

可以看到範例專案中 ValueController 底下有提供五個 API 接口，呼叫 API 時分別要透過 HTTP 的哪種 Method 方法以及 Route、Action Name 名稱，點擊 Method 會提供更多 API 細節

簡單說明 : 

• 1. API 註解 : 稍早在 Code 加上的註解 (XML) 已呈現在網頁，除此之外還列出此接口所需要的參數型別資訊
• 2. 測試接口 : 按下 Try it out，可以直接根據你所輸入的參數直接打 API 位置，方便驗證正確性
• 3. 測試回傳 : 可以看到打完 API 後回傳資訊，像是 Header 內容、Status Code、Response 物件

Summary
Swagger 幫助我們線上Web API Application 產生文件，透過一些簡單的設定加上 XML Remark就能夠達到這件事，讓寫文件這件事變得沒那麼無聊，這篇分享 Swagger 基本的操作說明及用法，之後預計會(咦 是拖稿嗎)在分享更多實務上遇到的情境需求及使用心得

參考
Swagger初探
swagger-ui
ASP.NET Web API 文件產生器 - 使用 Swagger

Related Posts:

• [WEBAPI] 如何設定 Swagger 為預設首頁 Start Page問題 自己不管是在開發 .NET Framework 或是 .NET Core 專案，只要遇到是 Web API 專案都會安裝 Swagger 來協助測試 API 的動作，只要使用過 Swagger 的開發者都知道啟動專案後第一件事就是要在開啟的頁面網址加上 Swagger，接著在繼續透過 Swagger 頁面進行 API 測試的動作，但每次開啟時就需要在網址上輸入一次也是頗麻煩的，今天就來分享兩種方式可以起始頁面為 swagger 頁面，若有問… Read More
• [C#] Web API - HttpClient 入門HttpClient 介紹 當在開發 Client 程式時，要取得呈現在畫面上的資料會與 API / Server 進行連線動作，在過去可以使用 WebClient 或者是 HttpWebRequest ，在 .NET Framework 4.5 開始微軟提供 HttpClient 類別給開發者使用，命名空間為 Sysyem.Net.Http，它提供靈活且可擴充的 API 來訪問 HTTP 公開的物件，發送 Request 跟… Read More
• [WEBAPI] Swagger - 用 Swashbuckle.Examples 加上有意義的測試數據 問題 Swagger 是一個可以將 WebAPI 快速文件化的套件，產生出來的線上文件除了可以列出 API 詳細資料外還可以直接在網頁上進行測試的動作，對開發者和接 API 的使用者來說十分方便，上一篇文章介紹了 Swagger 基本使用 說明，最近想要在公司內部推廣使用 Swagger 服務，資深同事提到過去有陣子曾經使用過 Swagger 服務，但  每次要使用 API 接口服務時參數 (params)… Read More
• [NETCore] ASP.NET Core 中加入 API 版本控制前言 在開發 API 時可能會因為代碼調整或是架構的演進，相同的 API 接口可能會有新的版本出現，為了不影響舊的呼叫端程式邏輯運作，就需要在代碼中加上新舊版本的對應來解決 API 版本問題，或許為了解決 API 版本問題可以有很多種不同的解法，在 ASP.NET Core 中可以透過  Microsoft.AspNetCore.Mvc.Versioning  來解決此問題，這篇就來分享一下有關M… Read More
• [NETCore] ASP.NET Core 中的例外處理方式前言 錯誤處理一直是開發中的重要環節之一，如果在程式發生異常錯誤的當下有效的將錯誤訊息完整的記錄下來，可以大大的節省 debug 的時間與效率，反過來如果在開發時沒有考慮到異常處理的機制，可能在發生問題時要找到錯誤的原因難度就會提高，因此在開發時必須要考慮到異常處理的機制，過去公司都會將 exception 訊息透過推(push)或是拉(pull)的方式傳送到 Logstash 再搭配 Elasticsearch 與 Kibana 搜尋到相對… Read More