1.前言

SwaggerUI 是一個簡單的Restful API 測試和文件工具。簡單、漂亮、易用（官方demo）。通過讀取JSON 配置顯示API. 專案本身僅僅也只依賴一些 html,css.js靜態檔案. 你可以幾乎放在任何Web容器上使用。

Swashbuckle 是.NET類庫,可以將WebAPI所有開放的控制器方法生成對應SwaggerUI的JSON配置。再通過SwaggerUI 顯示出來。類庫中已經包含SwaggerUI 。所以不需要額外安裝。

2.快速開始

• 建立專案 OnlineAPI來封裝百度音樂服務

  (示例下載) ，通過API可以搜尋、獲取音樂的資訊和播放連線。

我儘量刪除一些我們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跨平臺或掃描二維碼關注