ASP.NET WebAPI 自动生成帮助文档

当您创建一个Web API，建立了一个帮助页面非常有用。可以手动创建的所有文件，但最好是能够自动生成。

为了使这项工作更容易，ASP.NET Web API提供了自动生成帮助页面的模板，如下图



如何创建Help Page？

1、用VS2013创建的Web API 2项目会默认带有Microsoft ASP.NET Web API Help Page的包。如果没有，就需要手动去NuGet上安装。



2、 如果安装了这个包，创建新的Web API 项目后，Web API项目目录里会多一个Area，里面有个HelpPage文件夹，这里面放的都是HelpPage生成器的代码、页面模版和配置文件。



当你运行应用程序时，主页上包含一个链接到API帮助页面。





3、 “Description”字段的内容，是需要去配置的，Description的内容所使用的其实是代码里方法的注释，即/// <summary>形式的注释。这些东西是可以生成XML的，许多文档生成器都要使用这份XML作为metadata的来源。

在我们的网站里，这样的metadata信息通常应该放在App_Data文件夹里，而不是默认的bin目录里。所以我们要对Web API的项目属性做一些更改。

打开项目属性，在Build页面里，勾选XML documentation file，并把他放到App_Data下面：





取消Register方法中第一段代码的注释，并且把XML文件的路径改成刚才在刚才在项目属性页里设置的路径。

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/PatientView.Service.WebAPI.xml")));

现在，如果你在API方法上添加/// <summary>的注释，就会被生成在网页上。