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