1.3为WebApi创建帮助文档

当你创建一个网络 API 时，它很有用来创建一个帮助页，以便其他开发人员将知道如何调用您的 API。您可以创建的所有文档手动，但它是自动生成尽可能多地更好。

为了简化这一任务，ASP.NET Web API 提供一个库自动生成帮助页在运行时。

1.创建 API 帮助页

安装ASP.NET和Web Tools 2012.2 Update.此更新集成到 Web API 项目模板的帮助页面。

接下来，创建一个新的 ASP.NET MVC 4 项目并选择 Web API 项目模板。项目模板创建名为ValuesController的示例 API 控制器。该模板还创建 API 帮助页。所有的帮助页的代码文件放置在项目的区域文件夹。

当您运行该应用程序时，主页页面包含 API 的帮助页面的链接。从主页，相对路径是 /Help。

此链接为您带来了 API 的摘要页。

此页的 MVC 视图是在 Areas/HelpPage/Views/Help/Index.cshtml 中定义的。你可以编辑此页后，可以修改布局、 介绍、 标题、 风格等等。

该页面的主要部分是按照控制器分组的Api帮助表格。表格记录是根据IApiExplorer接口动态生成的。（我会稍后再谈谈此接口）。如果您添加一个新的 API 控制器，这个表格也会自动更新。

这个Api的列会列出Http方法和相对路径，Description列包含每个Api的描述。在下一节，我们可以看到如何从Xml文档添加注释。

每个Api有一个链接页面，提供更加详细的信息。包括请求体和响应体的示例。

2.将帮助页添加到现有的项目

你可以在一个已经存在的项目通过Nuget包管理器去添加帮助页面。

这个方法很有用，当你从新的一个项目而不在WebApi这个项目。

C#应用程序 ︰Install-Package Microsoft.AspNet.WebApi.HelpPage

Visual Basic应用程序 ︰Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

有两个包，一个用于 C# 和 Visual Basic 之一。请确保使用最符合您的项目。

这个命令就会安装必要的程序集并且为这些帮助页创建MVC视图（路径为Areas/HelpPage的文件夹）。所以你需要手动添加一个链接跳到帮助页面。

Url为/Help，在Razor视图创建链接，请添加以下内容：

@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

当然，也需要注册区域路由规则。

在Global.asax文件，在Application_Start方法添加以下代码，如果这不存在的话：

protected void Application_Start()
{
    // Add this code, if not present.
    AreaRegistration.RegisterAllAreas();5 
    // ...
}

3.添加Api文档

默认情况下，这个帮助页面由documentation去替换占位的文本，你也可以使用XML文档注释去创建documentation。

如果你要启用这个功能，你需要打开Areas/HelpPage/App_Start/HelpPageConfig.cs这个文件，以及注释以下行：

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

现在启用了XML文档，在解决方案资源管理器，右键单击该项目并选择属性，选择生成页。

 在输出下，XML文档文件的编辑框，在编辑框中，输入"App_Data/XmlDocument.xml"

 接下来，打开ValuesController的控制器/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";
}

提示：如果你的方法上方有三个斜杠，VS将自动插入XML的元素。

现在生成项目并且再次运行应用程序，并导航到帮助页。这些注释字符串应该会在Api的表格上显示。

这个帮助页就会从XML文件读取字符串，当你部署应用程序的时候，请确保XML文件是存在的。

4.Under the Hood

这些帮助页都是简历在ApiExplorer 类，它是WebApi框架的一部分。ApiExplorer 类提供了创建一个帮助页的工具。对于每个Api来说,ApiExplorer就会包含Api一些描述。

为了这个目的，Api就是定义组合的Http方法和相对的Url路径，例如，下面是一些不同的Api：

 

如果一个控制器动作支持多个 HTTP 方法， ApiExplorer会将每个方法视为不同的 API。

要隐藏从ApiExplorerAPI，将ApiExplorerSettings属性添加到操作，将IgnoreApi设置为 true。

 

[ApiExplorerSettings(IgnoreApi=true)]
public HttpResponseMessage Get(int id) {  }

也可以将此属性添加到要排除整个控制器的控制器。

ApiExplorer 类从IDocumentationProvider接口获取文档字符串。正如你看到的早些时候，帮助页面库提供从 XML 文档字符串中获取文件的IDocumentationProvider 。代码位于 /Areas/HelpPage/XmlDocumentationProvider.cs。通过编写您自己的IDocumentationProvider，你可以从另一个源获取文档。若要它捆绑起来，请在HelpPageConfigurationExtensions中定义的SetDocumentationProvider扩展方法

ApiExplorer自动调用IDocumentationProvider接口来获取每个 API 的文档字符串。它将它们存储在文档属性中的ApiDescription和ApiParameterDescription的对象。