Share via

为 ASP.NET Web API创建帮助页

  • 项目

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

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

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

创建 API 帮助页

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

接下来，创建一个新的 ASP.NET MVC 4 项目，并选择 Web API 项目模板。 项目模板创建名为 ValuesController的示例 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 中定义。 可以编辑此页面以修改布局、简介、标题、样式等。

页面main部分是按控制器分组的 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 文档文件的选项。

接下来，打开 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 表中。

帮助页中 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 并不局限于创建帮助页。 姚黄林已经写了一些伟大的博客文章，让你思考开箱即用：