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

原文更新日期：2013.04.01

导航页面

http://blog.csdn.net/wf824284257/article/details/79475115

上一步

在WebForm项目中使用Web API
http://blog.csdn.net/wf824284257/article/details/79449844

开始

当你创建了 web API 之后，再为它创建一个帮助页面是非常有用的，这样的话其他的开发者就可以知道如何调用你的API了。虽然你可以手动创建所有的帮助文档，但是如果可能的话，更好一点的方式是自动生成它们。

为了更方便的自动生成帮助页面，ASP.NET Web API 提供了一个可以在程序运行的时候自动生成帮助页面的库（library）。

########## 1

生成 API 帮助页面

使用VS2017的情况下，使用 Web API 模板创建的项目将会自动包含了帮助页面，所有的帮助页面的相关源码位于Areas->HelpPage。

############ 2

当你运行应用程序时，主页导航栏上会有一个“API”链接。相对于主页，API 帮助页面的路径是 “/Help”.

############### 3

“API”链接指向 API 帮助页面的概要页面（summary page）。

############## 4

该页面对应的MVC的view是“Areas/HelpPage/Views/Help/Index.cshtml”。你可以通过编辑这个页面来修改布局、介绍、标题、样式以及其他的一些东西。

该页面的主要部分是一个API的表格，其中的API根据controller来分组显示。这个表格的数据是动态生成的，使用了IApiExplorer接口（接下来我将会介绍更多的关于该接口的知识）。如果你添加了一个新的 API controller ，这个表格将会在程序运行的时候动态的更新。

表格中的 “API”列列出了HTTP请求的方法以及相对路径，“Description” 列的内容包含了每个API的文档文本。最初，这些文档文本只是一个占位文本。在下一小节教程中，我将会向你展示如何依据XML注释来给API添加文档文本。

每个API都有一个链接，链接页面包含了更多的关于该API的信息，包括示例请求及示例响应。

############ 5

向已存在的项目中添加API帮助页面

使用 NuGet Package Manager（NuGet包管理器），你可以向已存在的使用了 Web API 的项目中添加 API 帮助页面。如果你的项目不是使用 “Web API” 模板创建的话，那么这段教程对你来说是非常有帮助的。

从菜单的“工具”,找到“NuGet包管理器” ->”程序包管理器控制台”（Package Manager Console）。在该控制台窗口里，敲下以下命令行：

对于C#项目 ： Install-Package Microsoft.AspNet.WebApi.HelpPage
对于VB.NET项目： Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

这里有两个包，一个是给C#用的，另外一个是给VB用的。要确保你没有用错。

上面的命令行为我们的应用程序安装了必要的组件，并且以MVC views的形式添加了API 帮助页面（位于Areas/HelpPage文件夹）。你需要在你的主页手动的添加一个指向该帮助页面的链接，url为“/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文档文本

默认情况下，被创建出来的帮助页面上存在API文档文本的占位文本。你可以使用XML说明注释来创建这些文档文本。为了开启这个功能，打开“Areas/HelpPage/App_Start/HelpPageConfig.cs”并且为下面的代码取消注释：

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

现在XML文档文本已经可以使用了。在解决方案资源管理器（Solution Explorer）中，邮件点击项目名，选择属性（Properties）->生成（Build）。

############### 6

在“Output”（输出路径）下面，将“XML documentation file”(XML文档文件)打钩，并在后面的输入框中输入“App_Data/XmlDocument.xml”。

############ 7

然后，打开“/Controllers/ValuesControler.cs”，为其中的方法添加XML注释，比如：

/// <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";
}

注意：你可以直接输入3个’/’，接下来Visual Studio会自动插入XML注释元素，然后我们只需要填空即可。

现在编译并运行我们的程序，并导航到API帮助页面。可以看到刚刚我们写的XML注释文本显示在了API表格的“Description”一列。

########### 8

帮助页面会在程序运行的时候读取相应的XML文件。当你发布你的应用程序时，相关的XML文件也应该被一起发布。

深度理解

这些帮助页面是在“ApiExplorer”类（ Web API 框架的一部分）上建立起来的。“ApiExplorer”类为创建帮助页面提供了原材料，对于每个API，ApiExplorer包含了一个
ApiDescription来描述这个API。为了这个目的，一个“API”被定义为一个HTTP方法与一个相对路径的组合。举个例子，下面是一些互不相同的API：

GET /api/Products
GET /api/Products/{id}
POST /api/Products

如果一个controller的action支持多种HTTP方法，ApiExplorer 会认为这些方法是互不相同的。

为了从ApiExplorer 中隐藏一个API，需要为action添加以下特性：

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

你也可以将该特性添加给一个controller，这样就能将这个controller排除在外。

“ApiExplorer”类从“IDocumentationProvider”接口中获取文档文本。就像之前你所看到的，帮助页面的库中提供了一个 IDocumentationProvider，它可以从XML文档中取得文本。这些代码位于“/Areas/HelpPage/XmlDocumentationProvider.cs”。通过自己写一个IDocumentationProvider，你就可以从另一个数据源中取得文档文本。为了将它们联系起来，需要调用SetDocumentationProvider这个扩展方法，该方法定义在HelpPageConfigurationExtensions中。

ApiExplorer 会自动的调用IDocumentationProvider 接口来为每个API取得它的文档文本。ApiExplorer将这些文档文本存储在ApiDescription的Documentation属性以及ApiParameterDescription实体中。

下一步

结束

本文为微软官方文档的个人译文。本译文的非商用转载请注明地址及作者，感谢。禁止商用转载。若经发现，将依法追究责任。
英文原文地址：https://docs.microsoft.com/en-us/aspnet/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages
原文作者： MikeWasson and Other 4 Contributors
主作者链接：https://github.com/MikeWasson
作者尊重微软公司的知识产权，若贵公司认为该博客有损贵公司利益，请联系作者删除

译者：大吴凡 http://dawufan.cn