Use Swagger to build API description and test them in Webapi

 Webapi   API document

▌背景

---

偶然間又看到了KKBruce大的文章：ASP.NET Web API 文件產生器(2) - Swagger

因為專案中會時常產生一些說明文件給介接的AP，所以當然是很樂見到這些大大減少了工作負擔協助的工具。

如果您也好奇Swagger的話，可以直接參考KKBruce大的文章。

在這篇小弟只是記錄一下我學習的過程 XD

▌環境

---

l   Windows 7 Enterprise

l   Visual Studio 2013 update 5

l   Swashbuckle - Swagger for WebApi 5.2.1

▌實作

---

▋建立一WeApi專案

l   當然XML註解是一定要寫的啦~~

/// <summary> /// User(使用者)的Restful service /// </summary> public class UserController : ApiController {         /// <summary>         /// 取得所有使用者資訊         /// </summary>         /// <returns>Users</returns>         [HttpGet]         public IEnumerable<User> GetAll()         {             return (new List<User>() {                 new User{Name="JB", Address="Tainan", PhoneNumber="0933-XXX-XXX" },                 new User{Name="Lily", Address="Taipei", PhoneNumber="0910-XXX-XXX" },                 new User{Name="Leia", Address="Taiwan", PhoneNumber="0988-XXX-XXX" }             }).AsEnumerable();         }         /// <summary>         /// 取得特定使用者         /// </summary>         /// <param name="name">使用者名稱</param>         /// <returns>User</returns>         [HttpGet]         public User Get(String name)         {             throw new NotImplementedException();         }         /// <summary>         /// 新增使用者         /// </summary>         /// <param name="user">User</param>         [HttpPost]                public void Post(User user)         {             throw new NotImplementedException();         }         /// <summary>         /// 更新使用者         /// </summary>         /// <param name="user">User</param>         [HttpPut]         public void Put(User user)         {             throw new NotImplementedException();         }         /// <summary>         /// 刪除使用者         /// </summary>         /// <param name="name">使用者名稱</param>         [HttpDelete]         public void Delete(String name)         {             throw new NotImplementedException();         } }

l   開啟專案屬性，在建置頁籤的輸出中，勾選「XML文件檔案」。

▋安裝Nuget Package

Swashbuckle - Swagger for WebApi

▋指定輸出的XML註解文件位置

開啟【App_Start】→【SwaggerConfig.cs】；

找到原本已註解掉的此行程式碼：

//c.IncludeXmlComments(GetXmlCommentsPath());

反註解它，並實作getXmlCommentsPath() 這個方法。(我把第一個字改為小寫了)

c.IncludeXmlComments(getXmlCommentsPath());

private static string getXmlCommentsPath() { var xmlPath = string.Format(@"{0}\App_Data\MyWebapi.XML", System.AppDomain.CurrentDomain.BaseDirectory);     return xmlPath; }

▋測試（開啟localhost:port/swagger）

可以點選個方法進去查看細節(Model/Model Schema)

也可以直接測試該CRUD方法 …

之後如果有其他單位需要使用我們的API，就可以很快速地提供相關資訊了!

▌Reference

---

l   http://swagger.io/

l   ASP.NET Web API 文件產生器(2) - Swagger