转载地址:http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages
当创建web API 时,经常要创建一个帮助页,以便其他开发人员知道如何调用您的 API。您可以手动创建的所有文档,但最好是尽可能多地自动生成。
为了简化这一任务,ASP.NET Web API 提供一个库自动生成帮助页。
创建 API 帮助页
安装ASP.NET 和 Web 工具 2012.2 的更新。此更新集成到 Web API 项目模板的帮助页面。
接下来,创建一个新的 ASP.NET MVC 4 项目并选择 Web API 项目模板。项目模板创建名为ValuesController
的示例 API 控制器。该模板还会创建 API 的帮助页面。所有的帮助页的代码文件都放在项目的区域文件夹。
当您运行该应用程序时,主页页面包含 API 的帮助页面的链接。从主页上,相对路径是 /Help。
此链接为您带到 API 的摘要页。
此页的 MVC 视图是在 Areas/HelpPage/Views/Help/Index.cshtml 中定义的。您可以编辑此页后,可以修改布局、 介绍、 标题、 样式和等等。
该页面的主要部分是一个table布局的控制器的Api。使用IApiExplorer接口条目是动态生成的。(我会稍后再谈谈此接口)。如果您添加一个新的 API 控制器,在运行时自动更新的界面。
"API"列列出了 HTTP 方法和相对 URI。"说明"列中包含每个 API 的文档。最初,该文档是只是占位符文本。在接下来的部分中,我将展示如何从 XML 注释添加文档。
每个 API 已链接到一个网页提供更详细信息,包括示例请求和响应的代码。
将帮助页面添加到现有的项目
通过使用 NuGet 程序包管理器,可以将帮助页面添加现有 Web API 项目。
从工具菜单中,选择库程序包管理器,然后选择程序包管理器控制台。在程序包管理器控制台窗口中,键入下列命令之一:
C#应用程序:Install-Package Microsoft.AspNet.WebApi.HelpPage
此命令安装必要的程序集并添加 MVC 视图 (位于Area/HelpPage 文件夹)的帮助页。您需要手动添加到帮助页的链接。URI 是 /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 文档
默认情况下,帮助页面有文件的占位符字符串。您可以使用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"。
接下来,打开ValuesController
API 控制器,它在 /Controllers/ValuesControler.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 中。
帮助页在运行时从 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接口获取文档字符串。正如您看到的早些时候,帮助页面库提供了从 XML 文档字符串中获取文件的IDocumentationProvider 。该代码位于 /Areas/HelpPage/XmlDocumentationProvider.cs。通过编写您自己的IDocumentationProvider,可以从另一个源获取文档。若要它捆绑起来,请在HelpPageConfigurationExtensions中定义的SetDocumentationProvider扩展方法
ApiExplorer自动调用IDocumentationProvider接口来获取每个 API 的文档字符串。它将它们存储在文档属性中的ApiDescription和ApiParameterDescription的对象。