如何使 WebAPI 自動生成漂亮又實用在線API文檔

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/

 

相關文章：

• WebAPI前置知識:HTTP與RestfulAPI

• WEB API系列（一）：WEB API的適用場景、第一個實例

• WEB API 系列（二） Filter的使用以及執行順序

• ASP.NET Web API 安全篩選器

• Web API 基於ASP.NET Identity的Basic Authentication

• ASP.NET Web Api使用CacheCow和ETag緩存資源

• 使用 West Wind WebSurge 對 ASP.NET Web API 服務進行壓力測試

• Web API應用支持HTTPS的經驗總結

• Dion Hinchcliffe談Web API的過去與將來

• WebAPI生成可導入到PostMan的數據

 

原文地址：http://www.cnblogs.com/Arrays/p/5146194.html

---

.NET社區新聞，深度好文，微信中搜索dotNET跨平臺或掃描二維碼關注