为 ASP.NET Web API 创建帮助页面

转载地址：http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages

当创建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 中定义的。您可以编辑此页后，可以修改布局、 介绍、 标题、 样式和等等。

该页面的主要部分是一个table布局的控制器的Api。使用IApiExplorer接口条目是动态生成的。(我会稍后再谈谈此接口)。如果您添加一个新的 API 控制器，在运行时自动更新的界面。

"API"列列出了 HTTP 方法和相对 URI。"说明"列中包含每个 API 的文档。最初，该文档是只是占位符文本。在接下来的部分中，我将展示如何从 XML 注释添加文档。

每个 API 已链接到一个网页提供更详细信息，包括示例请求和响应的代码。

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

通过使用 NuGet 程序包管理器，可以将帮助页面添加现有 Web API 项目。

从工具菜单中，选择库程序包管理器，然后选择程序包管理器控制台。在程序包管理器控制台窗口中，键入下列命令之一：

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

此命令安装必要的程序集并添加 MVC 视图 （位于Area/HelpPage 文件夹）的帮助页。您需要手动添加到帮助页的链接。URI 是 /Help。要在 razor 视图中创建链接，请添加以下内容：

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

此外，还要确保要注册的Area。在 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"。

接下来，打开ValuesController API 控制器，它在 /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/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接口获取文档字符串。正如您看到的早些时候，帮助页面库提供了从 XML 文档字符串中获取文件的IDocumentationProvider 。该代码位于 /Areas/HelpPage/XmlDocumentationProvider.cs。通过编写您自己的IDocumentationProvider，可以从另一个源获取文档。若要它捆绑起来，请在HelpPageConfigurationExtensions中定义的SetDocumentationProvider扩展方法

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