为 ASP.NET Web API创建帮助页
本教程包含代码演示如何为 ASP.NET 4.x 中的 ASP.NET Web API创建帮助页。
创建 Web API 时，创建帮助页通常很有用，以便其他开发人员知道如何调用你的 API。 可以手动创建所有文档，但最好尽可能自动生成文档。 为了简化此任务，ASP.NET Web API提供了一个库，用于在运行时自动生成帮助页。
创建 API 帮助页
安装 ASP.NET 和 Web 工具 2012.2 更新。 此更新将帮助页集成到 Web API 项目模板中。
接下来，创建一个新的 ASP.NET MVC 4 项目，并选择 Web API 项目模板。 项目模板创建名为 ValuesController的示例 API 控制器。 该模板还会创建 API 帮助页。 帮助页的所有代码文件都放置在项目的“区域”文件夹中。
运行应用程序时，主页包含指向 API 帮助页的链接。 在主页中，相对路径为 /Help。
此链接将介绍 API 摘要页。
此页面的 MVC 视图在 Areas/HelpPage/Views/Help/Index.cshtml 中定义。 可以编辑此页面以修改布局、简介、标题、样式等。
页面main部分是按控制器分组的 API 表。 表条目是使用 IApiExplorer 接口动态生成的。 (稍后将详细介绍此接口。) 如果添加新的 API 控制器，表将在运行时自动更新。
“API”列列出了 HTTP 方法和相对 URI。 “说明”列包含每个 API 的文档。 最初，文档只是占位符文本。 在下一部分中，我将演示如何从 XML 注释添加文档。
每个 API 都有一个指向页面的链接，其中包含更详细的信息，包括示例请求和响应正文。
向现有项目添加帮助页
可以使用 NuGet 包管理器将帮助页添加到现有 Web API 项目。 此选项可用于从与“Web API”模板不同的项目模板开始。
在 “工具 ”菜单中，选择“ NuGet 包管理器”，然后选择“ 包管理器控制台”。 在 “包管理器控制台” 窗口中，键入以下命令之一：
对于 C# 应用程序： Install-Package Microsoft.AspNet.WebApi.HelpPage
对于 Visual Basic 应用程序： Install-Package Microsoft.AspNet.WebApi.HelpPage.VB
有两个包，一个用于 C#，一个用于 Visual Basic。 请确保使用与项目匹配的那个。
此命令安装必要的程序集，并为位于 Areas/HelpPage 文件夹) (帮助页添加 MVC 视图。 需要手动添加指向“帮助”页的链接。 URI 为 /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();
// ...
}
添加 API 文档
默认情况下，帮助页具有文档的占位符字符串。 可以使用 XML 文档注释 来创建文档。 若要启用此功能，请打开文件 Areas/HelpPage/App_Start/HelpPageConfig.cs 并取消注释以下行：
config.SetDocumentationProvider(new XmlDocumentationProvider(
HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));
现在启用 XML 文档。 在“解决方案资源管理器”中，右键单击项目并选择“属性”。 选择“ 生成 ”页。
在“输出”下，检查 XML 文档文件。 在编辑框中，键入“App_Data/XmlDocument.xml”。
接下来，打开 API 控制器的代码，该代码 ValuesController 在 /Controllers/ValuesController.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/Products
- GET /api/Products/{id}
- POST /api/Products
如果控制器操作支持多个 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 从其他源获取文档。 若要连接它，请调用 HelpPageConfigurationExtensions 中定义的 SetDocumentationProvider 扩展方法
ApiExplorer 自动调用 IDocumentationProvider 接口，以获取每个 API 的文档字符串。 它将它们存储在 ApiDescription 和 ApiParameterDescription 对象的 Documentation 属性中。
后续步骤
不限于此处显示的帮助页。 事实上， ApiExplorer 并不局限于创建帮助页。 姚黄林已经写了一些伟大的博客文章，让你思考开箱即用：