2016年2月18日
本文旨在介紹如何使用常用的 swagger 和 swashbuckle 架構建立描述 restful api 的互動界面，并為 api 使用者提供豐富的探索、檔案和操作體驗。
在本文中，我們将在 asp.net 建立一個簡單的 restful api，并整合 swashbuckle 和 swagger ui。本文分為三部分。
建立 asp.net web api項目
通過實體資料模型 （.edmx） 和 scaffold api控件連接配接到 sql server資料庫
整合 swashbuckle/swagger ui架構以描述 api 操作
首先建立一個新的“asp.net web應用”，将其命名為“swagger”
從模闆中選擇 web api，也就是說， visual studio将把 mvc、與web api相關的檔案夾和核心引用添加到我們的應用中。然後，點選“更改權限”，選擇“無權限”後點選ok。通過以上設定，我們将跳過項目中與賬戶相關的控件和視圖。
執行 visual studio 啟動程式後，項目文檔和檔案夾的結構如下：
我們将在應用 app_start 檔案夾中将 mvc 控件的路徑設定為 routeconfig.cs ，将web api控件的路徑設定為 webapiconfig.cs 。
注：你可以在該區域看到“幫助頁”檔案夾。此檔案夾将包含 visual studio 生成的模型、視圖、控件和其他與幫助相關的文檔，以描述web api幫助。我們将在下文對這一問題進行分析。
如果檢視 nuget 包管理器中的“已安裝包”，你會發現項目中已經添加了“microsoft asp.net web api 2.2 幫助頁”包、razor包和核心包。
我們先通過實體資料模型将應用連接配接到資料庫表。首先，建立新的“ado.net實體資料模型”項目，在模型檔案夾中将其命名為 “swaggermodel”。
從向導中選擇“資料庫中的 ef designer”，并點選“下一步”連接配接到資料庫伺服器（此處即為sql server）。
在實體資料模型向導頁面中，選擇連接配接到 sql server，并将連接配接字元串命名為“swaggerconstr”，該字元串将儲存在web.config文檔中。
點選“下一步”，選擇實體架構版本（即本文中的6.x）。點選“下一步”，選擇edmx公司表，将其儲存在edmx文檔中。
選擇表格，點選“完成”按鍵，最後會生成poco類“company.cs”和資料庫配置指令類“swaggerconstr” 。
現在已經建立了實體資料模型和配置指令，那麼我們可以通過visual studio支架特性建立新的api控件。但為了充分利用配置指令，在給 api 控件建立支架前，我們應先建立應用。即在建立支架之前，删除控件檔案夾中現有的valuescontroller.cs。
點選控件檔案夾，并添加“控件…”，即打開帶有各種支架選項的“添加支架”視窗，選擇“web api 2 controller with actions, using entity framework（帶有動作、使用實體架構的web api 2控件”，然後點選“添加”。
在添加控件視窗中選擇模型（即本文的company.cs）以及資料配置指令類（swaggerconstr.cs）。将新控件命名為“companycontroller.cs”，并點選“添加”。
為每個http 動作（get, put, post and delete）操作建立的新控件如下：
建立和運作應用後，可看到如下截圖。你可以在使用者界面頂端導航中看到“api”連結，點選後進入“asp.net api幫助頁”頁面。幫助首頁如下所示。
注：為了檢查api，應在url中添加“/api/company”，并在浏覽器中送出。
點選任意操作連結後将顯示更多詳情，如帶有uri、本體參數的“請求”資訊、“響應”類型、json或xml等格式。下圖為get方法截圖：
雖然visual studio團隊花費了很大精力為這項服務的消費者展示web api幫助，但這項服務的薄弱點是使用者界面過于基礎，而且我們無法使用動作方法。這正是有必要使用swagger ui & swashbuckle的原因。
點選進入“ manage nuget packages…（管理nuget包）”，并線上搜尋“swashbuckle”。在清單中選擇richard morris建立的5.2.2版 “swashbuckle - swagger for web api”，點選安裝。
這一操作會将引用添加到“swashbuckle - swagger for web api”與“swashbuckle.core - swagger for web api”中。且後者會在經過依賴檢查後添加到我們的項目中。在packages.config中也是如此。
成功安裝後，我們可以在app_start檔案夾中看到一個新的“swaggerconfig.cs”配置文檔，所有swagger相關配置都會在此進行設定。
為了能直接連結到swagger api 接口，應将下列所有動作連結到“_layout.cshtml”頁面的頂部導航欄。
現在，建立并運作應用。點選頂部導航的“swagger help”後進入swagger使用者界面。點選清單操作（list operations），檢視所有互動指令操作及相應的動詞。
點選操作後會顯示響應類别。點選“try it out（試試看）!”按鍵後可顯示請求url、響應體、響應代碼和響應頭等細節。
get操作:
post操作細節:
删除操作細節:
通過id進行get操作的細節:
put操作細節:
點選進入項目屬性，在建立标簽下的輸出區勾選“xml documentation file（xml文檔檔案）:”後，即可在儲存文檔的二進制檔案夾中看到 xml 路徑。
接着打開swagger配置文檔，并添加 “includexmlcomments”語句，該語句可将路徑從二進制檔案夾傳回至 xml 文檔。
在swaggerconfig.cs register靜态方法中啟用全局配置的方式如下：
用以下注解編輯控件get方法，可檢查 xml 注解是否運作：
運作應用，并通過頂部導航欄導航到swagger幫助頁面。随後可看到添加到swagger幫助頁面的xml注解。
swashbuckle檔案規定開發者可用預定義的 “injectstylesheet” 方法，将自定義 .css檔案作為嵌入式資源注入。我們需要将檔案的“logical name（邏輯名稱）”作為第二個參數，“media=screen”作為第三個可選參數，目前裝配作為第一個參數。
在内容檔案夾中建立一個新的名為 “mystyle.css”的css檔案，并通過添加以下樣式将标題預設背景色從綠色改成藍色。
右鍵點選文檔，選擇屬性，并将其build操作設定為“嵌入式資源”
現在，将以下代碼添加到 swagger 配置設定中，以啟動使用者界面：
注:樣式表單檔案的“邏輯名稱”。
現在運作應用，觀察變化。
swashbuckle 檔案規定開發者可用預定義的injectjavascript” 方法，将自定義的javascript 檔案作為嵌入式資源注入。我們要将文檔的 “logical name ”作為第二參數，将目前裝配作為第一參數。
在腳本檔案夾中建立新的 javascript 檔案 “myscript.js” ，并添加以下基本腳本，這樣檔案加載時可顯示自定義的告警消息。
右鍵點選文檔，選擇屬性，将其build操作設定為“嵌入式資源”
現在将以下代碼添加到 swagger 配置設定中，以啟動使用者界面：
注: java 描述檔案的“邏輯名稱”。
運作應用，以檢視告警消息：
最後， swaggerconfig register 方法檔案如下所示：
還有其它的定制方法，筆者今後将更新本文。
檢視筆者關于 asp.net mvc 、 web api 、 angular 等的其它文章：
<a href="http://www.codeproject.com/articles/815916/create-an-asp-net-web-forms-application-using-boot">使用bootstrap和web api建立 asp.net web表單應用</a>
<a href="http://www.codeproject.com/articles/821445/create-a-responsive-html-table-using-footable-and">使用 footable 建立響應式 html 表并使用 handlebars.js 應用用戶端綁定</a>
<a href="http://www.codeproject.com/articles/1059870/use-dependency-injector-ninject-to-dynamically-cho">通過依賴注入器 "ninject" 在 orm （實體架構或 dapper ）和資料庫（ sql 伺服器或oracle 資料庫）之間進行動态選擇</a>
<a href="http://www.codeproject.com/articles/988129/first-angularjs-application-using-asp-net-mvc-http">使用 asp.net mvc、 $http 和 $window services、ef和 crud 實作的首個 angularjs 應用</a>
<a href="http://www.codeproject.com/articles/1011666/baby-steps-towards-asp-net-web-application-and-see">逐漸解決 asp.net 5 web應用并了解新現象</a>