1.前言
1.1 SwaggerUI
SwaggerUI 是一個簡單的Restful API 測試和文檔工具。簡單、漂亮、易用（官方demo）。通過讀取JSON 配置顯示API. 項目本身僅僅也只依賴一些 html,css.js靜態文件. 你可以幾乎放在任何Web容器上使用。
1.2 Swashbuckle
Swashbuckle 是.NET類庫,可以將WebAPI所有開放的控制器方法生成對應SwaggerUI的JSON配置。再通過SwaggerUI 顯示出來。類庫中已經包含SwaggerUI 。所以不需要額外安裝。
2.快速開始
-
創建項目 OnlineAPI來封裝百度音樂服務(示例下載) ，通過API可以搜索、獲取音樂的信息和播放連接。
我盡量刪除一些我們demo中不會用到的一些文件，使其看上去比較簡潔。
-
WebAPI 安裝 Swashbuckle
Install-Package Swashbuckle -
代碼注釋生成文檔說明。
Swashbuckle 是通過生成的XML文件來讀取注釋的，生成 SwaggerUI，JSON 配置中的說明的。
安裝時會在項目目錄 App_Start 文件夾下生成一個 SwaggerConfig.cs 配置文件，用於配置 SwaggerUI 相關展示行為的。如圖：
-
將配置文件大概99行注釋去掉並修改為
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));-
並在當前類中添加一個方法
/// ///
/// /// protected static string GetXmlCommentsPath(string name){ return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name); }
-
緊接着你在此Web項目屬性生成選卡中勾選 “XML 文檔文件”，編譯過程中生成類庫的注釋文件
-
添加百度音樂 3個API
-
訪問
http:///swagger/ui/index,最終顯示效果
-
我們通過API 測試API 是否成功運行
3.添加自定義HTTP Header
在開發移動端 API時常常需要驗證權限，驗證參數放在Http請求頭中是再好不過了。WebAPI配合過濾器驗證權限即可
首先我們需要創建一個 IOperationFilter 接口的類。IOperationFilter
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法類添加一行注冊代碼
c.OperationFilter();添加Web權限過濾器
在你想要的ApiController 或者是 Action 添加過濾器
[AccessKey]最終顯示效果
4.顯示上傳文件參數
SwaggerUI 有上傳文件的功能和添加自定義HTTP Header 做法類似，只是我們通過特殊的設置來標示API具有上傳文件的功能
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法類添加一行注冊代碼
c.OperationFilter();
API 文檔展示效果
5.版本和資源
你可以通過下列連接獲取相關說明。
OnlineAPI Demo 項目下載
OnlineAPI Demo下載
Swashbuckle 項目地址：
https://github.com/domaindrivendev/Swashbuckle
swagger-ui 項目地址：
https://github.com/swagger-api/swagger-ui
swagger-ui 官網地址：
http://swagger.io/swagger-ui/
相關文章：
原文地址：http://www.cnblogs.com/Arrays/p/5146194.html
.NET社區新聞，深度好文，微信中搜索dotNET跨平台或掃描二維碼關注
