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服务的描述 发布 消费 虚拟化等特定的完整的实现，总体目标是使客户端和文档系统与服务器以同样的速度进行更新。