Web API 2 入门——创建ASP.NET Web API的帮助页面（谷歌翻译）

在这篇文章中

作者：Mike Wasson

创建Web API时，创建帮助页面通常很有用，以便其他开发人员知道如何调用API。您可以手动创建所有文档，但最好尽可能自动生成。

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

创建API帮助页面

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

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

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

此链接将带您进入API摘要页面。

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

页面的主要部分是由控制器分组的API表格。使用IApiExplorer接口动态生成表条目。（稍后我会再谈谈这个界面。）如果添加了一个新的API控制器，表将在运行时自动更新。

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

每个API都有一个包含更详细信息的页面的链接，包括示例请求和响应实体。

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

您可以使用NuGet软件包管理器将帮助页面添加到现有的Web API项目。从“Web API”模板的不同项目模板开始，此选项很有用。

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

对于C＃应用程序：Install-Package Microsoft.AspNet.WebApi.HelpPage

对于Visual Basic应用程序：Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

有两个包，一个用于C＃，一个用于Visual Basic。确保使用与您的项目匹配的。

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

CSHTML

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

另外，请务必注册区域。在Global.asax文件中，将以下代码添加到Application_Start方法中（如果还没有）：

C＃

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

    // ...
}

添加API文档

默认情况下，帮助页面具有用于文档的占位符字符串。您可以使用XML文档注释来创建文档。要启用此功能，请打开文件区域/ HelpPage / App_Start / HelpPageConfig.cs并取消注释以下行：

C＃

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

现在启用XML文档。在解决方案资源管理器中，右键单击项目并选择属性。选择构建页面。

在输出下，检查XML文档文件。在编辑框中，键入“App_Data / XmlDocument.xml”。1

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

C＃

/// <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 /产品
GET / api / Products / {id}
POST / api /产品

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

要从ApiExplorer中隐藏API ，请将ApiExplorerSettings属性添加到操作中，并将IgnoreApi设置为true。

C＃

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

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

ApiExplorer类从IDocumentationProvider接口获取文档字符串。如前所述，帮助页面库提供了一个IDocumentationProvider，它从XML文档字符串中获取文档。代码位于/Areas/HelpPage/XmlDocumentationProvider.cs中。您可以通过编写自己的IDocumentationProvider从其他来源获取文档。要连接它，调用SetDocumentationProvider扩展方法，在HelpPageConfigurationExtensions中定义

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