做者：Mike Wassonhtml
建立Web API时，建立帮助页面一般颇有用，以便其余开发人员知道如何调用API。您能够手动建立全部文档，但最好尽量自动生成。git
为了简化此任务，ASP.NET Web API提供了一个用于在运行时自动生成帮助页面的库。github
建立API帮助页面
安装ASP.NET和Web Tools 2012.2更新。此更新将帮助页面集成到Web API项目模板中。web
接下来，建立一个新的ASP.NET MVC 4项目并选择Web API项目模板。项目模板建立一个名为API的例子ValuesController。该模板还建立API帮助页面。帮助页面的全部代码文件都放在项目的区域文件夹中。api
运行应用程序时，主页包含指向API帮助页面的连接。在主页上，相对路径为/ Help。框架
此连接将带您进入API摘要页面。ide
该页面的MVC视图在Areas / HelpPage / Views / Help / Index.cshtml中定义。您能够编辑此页面来修改布局，介绍，标题，样式等。工具
页面的主要部分是由控制器分组的API表格。使用IApiExplorer接口动态生成表条目。（稍后我会再谈谈这个界面。）若是添加了一个新的API控制器，表将在运行时自动更新。布局
“API”列列出了HTTP方法和相对URI。“说明”列包含每一个API的文档。最初，文档只是占位符文本。在下一节中，我将介绍如何从XML注释中添加文档。this
每一个API都有一个包含更详细信息的页面的连接，包括示例请求和响应实体。
将帮助页面添加到现有项目
您可使用NuGet软件包管理器将帮助页面添加到现有的Web API项目。从“Web API”模板的不一样项目模板开始，此选项颇有用。
从工具菜单中，选择库包管理器，而后选择包管理器控制台。在“ 管理器管理器”窗口中，键入如下命令之一：
对于C＃应用程序：Install-Package Microsoft.AspNet.WebApi.HelpPage
对于Visual Basic应用程序：Install-Package Microsoft.AspNet.WebApi.HelpPage.VB
有两个包，一个用于C＃，一个用于Visual Basic。确保使用与您的项目匹配的。
此命令安装必要的程序集，并为帮助页面（位于Areas / HelpPage文件夹中）添加MVC视图。您须要手动添加一个连接到帮助页面。URI是/ Help。要在剃刀视图中建立连接，请添加如下内容：
@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)
另外，请务必注册区域。在Global.asax文件中，将如下代码添加到Application_Start方法中（若是尚未）：
protected void Application_Start() { // Add this code, if not present. AreaRegistration.RegisterAllAreas(); // ... }
添加API文档
默认状况下，帮助页面具备用于文档的占位符字符串。您可使用XML文档注释来建立文档。要启用此功能，请打开文件区域/ HelpPage / App_Start / HelpPageConfig.cs并取消注释如下行：
config.SetDocumentationProvider(new XmlDocumentationProvider( HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));
如今启用XML文档。在解决方案资源管理器中，右键单击项目并选择属性。选择构建页面。
在输出下，检查XML文档文件。在编辑框中，键入“App_Data / XmlDocument.xml”。1
接下来，打开ValuesControllerAPI控制器的代码，该控件在/Controllers/ValuesControler.cs中定义。向控制器方法添加一些文档注释。例如：
/// <summary> /// Gets some very important data from the server. /// </summary> public IEnumerable<string> Get() { return new string[] { "value1", "value2" }; } /// <summary> /// Looks up some data by ID. /// </summary> /// <param name="id">The ID of the data.</param> public string Get(int id) { return "value"; }
注意
提示：若是将插入符号放置在方法上方，并键入三个正斜杠，Visual Studio将自动插入XML元素。而后你能够填写空白。
如今再次构建和运行应用程序，并导航到帮助页面。文档字符串应显示在API表中。
帮助页面在运行时从XML文件读取字符串。（部署应用程序时，请确保部署XML文件。）
在敞篷下
帮助页面创建在ApiExplorer类之上，该类是Web API框架的一部分。该ApiExplorer类提供的原料，用于建立一个帮助页面。对于每一个API，ApiExplorer包含一个描述API 的ApiDescription。为此，将“API”定义为HTTP方法和相对URI的组合。例如，这里有一些不一样的API：
- GET / api /产品
- GET / api / Products / {id}
- POST / api /产品
若是控制器操做支持多种HTTP方法，则ApiExplorer将每一个方法视为不一样的API。
要从ApiExplorer中隐藏API ，请将ApiExplorerSettings属性添加到操做中，并将IgnoreApi设置为true。
[ApiExplorerSettings(IgnoreApi=true)] public HttpResponseMessage Get(int id) { }
您也能够将此属性添加到控制器，以排除整个控制器。
ApiExplorer类从IDocumentationProvider接口获取文档字符串。如前所述，帮助页面库提供了一个IDocumentationProvider，它从XML文档字符串中获取文档。代码位于/Areas/HelpPage/XmlDocumentationProvider.cs中。您能够经过编写本身的IDocumentationProvider从其余来源获取文档。要链接它，调用SetDocumentationProvider扩展方法，在HelpPageConfigurationExtensions中定义
ApiExplorer自动调用IDocumentationProvider接口获取每一个API的文档字符串。它将它们存储在ApiDescription和ApiParameterDescription对象的Documentation属性中。