[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