标签：
当你创建一个网络 API 时，它很有用来创建一个帮助页，以便其他开发人员将知道如何调用您的 API。您可以创建的所有文档手动，但它是自动生成尽可能多地更好。
为了简化这一任务，ASP.NET Web API 提供一个库自动生成帮助页在运行时。
安装ASP.NET和Web Tools 2012.2 Update.此更新集成到 Web API 项目模板的帮助页面。
接下来，创建一个新的 ASP.NET MVC 4 项目并选择 Web API 项目模板。项目模板创建名为ValuesController的示例 API 控制器。该模板还创建 API 帮助页。所有的帮助页的代码文件放置在项目的区域文件夹。
当您运行该应用程序时，主页页面包含 API 的帮助页面的链接。从主页，相对路径是 /Help。
此链接为您带来了 API 的摘要页。
此页的 MVC 视图是在 Areas/HelpPage/Views/Help/Index.cshtml 中定义的。你可以编辑此页后，可以修改布局、 介绍、 标题、 风格等等。
该页面的主要部分是按照控制器分组的Api帮助表格。表格记录是根据IApiExplorer接口动态生成的。（我会稍后再谈谈此接口）。如果您添加一个新的 API 控制器，这个表格也会自动更新。
这个Api的列会列出Http方法和相对路径，Description列包含每个Api的描述。在下一节，我们可以看到如何从Xml文档添加注释。
每个Api有一个链接页面，提供更加详细的信息。包括请求体和响应体的示例。
你可以在一个已经存在的项目通过Nuget包管理器去添加帮助页面。
这个方法很有用，当你从新的一个项目而不在WebApi这个项目。
C#应用程序 ︰Install-Package Microsoft.AspNet.WebApi.HelpPage
Visual Basic应用程序 ︰Install-Package Microsoft.AspNet.WebApi.HelpPage.VB
有两个包，一个用于 C# 和 Visual Basic 之一。请确保使用最符合您的项目。
这个命令就会安装必要的程序集并且为这些帮助页创建MVC视图（路径为Areas/HelpPage的文件夹）。所以你需要手动添加一个链接跳到帮助页面。
Url为/Help，在Razor视图创建链接，请添加以下内容：
1 @Html.ActionLink("API", "Index", "Help", new { area = "" }, null)
当然，也需要注册区域路由规则。
在Global.asax文件，在Application_Start方法添加以下代码，如果这不存在的话：
1 protected void Application_Start()
2 {
3 // Add this code, if not present.
4 AreaRegistration.RegisterAllAreas();5
6 // ...
7 }
默认情况下，这个帮助页面由documentation去替换占位的文本，你也可以使用XML文档注释去创建documentation。
如果你要启用这个功能，你需要打开Areas/HelpPage/App_Start/HelpPageConfig.cs这个文件，以及注释以下行：
1 config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));
现在启用了XML文档，在解决方案资源管理器，右键单击该项目并选择属性，选择生成页。
在输出下，XML文档文件的编辑框，在编辑框中，输入"App_Data/XmlDocument.xml"
接下来，打开ValuesController的控制器/Controllers/ValuesControler.cs，在控制器方法上添加一些注释，例如：
1 /// <summary>
2 /// Gets some very important data from the server.
3 /// </summary>
4 public IEnumerable<string> Get()
5 {
6 return new string[] { "value1", "value2" };
7 }
8
9 /// <summary>
10 /// Looks up some data by ID.
11 /// </summary>
12 /// <param name="id">The ID of the data.</param>
13 public string Get(int id)
14 {
15 return "value";
16 }
提示：如果你的方法上方有三个斜杠，VS将自动插入XML的元素。
现在生成项目并且再次运行应用程序，并导航到帮助页。这些注释字符串应该会在Api的表格上显示。
这个帮助页就会从XML文件读取字符串，当你部署应用程序的时候，请确保XML文件是存在的。
这些帮助页都是简历在ApiExplorer 类，它是WebApi框架的一部分。ApiExplorer 类提供了创建一个帮助页的工具。对于每个Api来说,ApiExplorer就会包含Api一些描述。
为了这个目的，Api就是定义组合的Http方法和相对的Url路径，例如，下面是一些不同的Api：
如果一个控制器动作支持多个 HTTP 方法， ApiExplorer会将每个方法视为不同的 API。
要隐藏从ApiExplorerAPI，将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的对象。
标签：
原文地址：http://www.cnblogs.com/shiningrise/p/5647525.html
