ASP.NET WebAPI 生成幫助文檔與使用Swagger服務測試

幫助HELP

要實現如WCF中的Help幫助文檔，Web API 2 中已經支持很方便的實現了這一特性  http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages

 Nuget獲得

Install-Package Microsoft.AspNet.WebApi.HelpPage

安裝完成后在 Areas/HelpPage/App_Start/HelpPageConfig.cs中啟用第一段注釋的代碼

public static void Register(HttpConfiguration config) { // Uncomment the following to use the documentation from XML documentation file. 
      config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml"))); }

然后在項目屬性，在Build頁面里，勾選XML documentation file

訪問

如果你要忽略一個方法API文檔，只需要加上忽略特性。

[ApiExplorerSettings(IgnoreApi=true)]

使用Swagger

測試Rest服務的工具很多，如FF下的 RESTClient，HttpRequester ，PostMan；Fiddler，SoapUI 等等；但是使用Swashbuckle 可以快速在項目中快速測試

https://github.com/domaindrivendev/Swashbuckle
Install-Package Swashbuckle 訪問/swagger

需要生成XML注釋只需要修改SwaggerConfig

var path = System.IO.Path.Combine(System.Web.HttpRuntime.AppDomainAppPath, "./App_Data/XmlDocument.xml"); c.IncludeXmlComments(path);

Swagger, Blueprint和RAML三種API設計比較

API Blueprint：提供跨越API整個周期的驚奇的工具，這樣可以和別人討論你的API，可以產生自動文檔或一個測試案例。

RAML：是一種RESTful API建模語言(RESTful API Modeling Language :RAML)， 它鼓勵重用 激活發現和模式分享，定位在最佳實踐的最優實現。

Swagger： 是一種針對RESTful Web服務的描述 發布 消費 虛擬化等特定的完整的實現，總體目標是使客戶端和文檔系統與服務器以同樣的速度進行更新。

Refer:
http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages
http://blogs.msdn.com/b/yaohuang1/archive/2013/01/20/design-time-generation-of-help-page-or-proxy-for-asp-net-web-api.aspx
Swagger簡介
http://blog.csdn.net/wangnan9279/article/details/44541665
RESTful風格的Web服務框架:Swagger
http://blog.163.com/xh_ding/blog/static/193903289201411592759809/