通过

为 ASP.NET Web API 创建帮助页

本教程包含代码演示如何在 ASP.NET 4.x 中创建 ASP.NET Web API 的帮助页。

创建 Web API 时，创建帮助页通常很有用，以便其他开发人员知道如何调用 API。 可以手动创建所有文档，但最好尽可能自动生成。 为了简化此任务，ASP.NET Web API 提供了一个库，用于在运行时自动生成帮助页。

“A S P 点 NET A P I 帮助”页的屏幕截图，其中显示了可供选择的可用 A P I 产品及其说明。

创建 API 帮助页

安装 ASP.NET 和 Web 工具 2012.2 更新。 此更新将帮助页集成到 Web API 项目模板中。

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

Web A P I 项目模板菜单选项的屏幕截图，将区域和帮助页面文件夹包围在一起。

运行应用程序时，主页包含 API 帮助页的链接。 在主页中，相对路径为 /Help。

主页的屏幕截图，指向将打开帮助页面链接的 A P I 可单击字母。

此链接将转到 API 摘要页。

“A P I 摘要帮助”页的屏幕截图，其中显示了不同的 A P I 值及其说明。

此页面的 MVC 视图在 Areas/HelpPage/Views/Help/Index.cshtml 中定义。 可以编辑此页面以修改布局、简介、标题、样式等。

页面的主要部分是 API 表，按控制器分组。 使用 IApiExplorer 接口动态生成表项。 （稍后我将讨论此接口的详细信息）。如果添加新的 API 控制器，则表在运行时自动更新。

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

每个 API 都有指向一个页面的链接，其中包含更详细的信息，包括示例请求和响应正文。

A P I 选择值之一的屏幕截图，其中显示了响应信息和响应正文格式。

向现有项目添加帮助页

可以使用 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”。

“输出”对话框的屏幕截图，其中显示了输出路径和选择 X M L 文档文件的选项。

接下来，打开在 /Controllers/ValuesController.cs 中定义的 API 控制器的代码 ValuesController 。 向控制器方法添加一些文档注释。 例如：

/// <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 表中。

帮助页中 A P I 表的屏幕截图，其中显示了 A P I 值和说明中的文档字符串。

帮助页在运行时从 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 不限于创建帮助页。 姚黄林已经写了一些精彩的博客文章，能启发你跳出框框思考：

  • Last updated on