为 ASP.NET Web API 创建帮助页面(转载)

时间:2024-01-04 21:18:56

转载地址:http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages

当创建web API 时,经常要创建一个帮助页,以便其他开发人员知道如何调用您的 API。您可以手动创建的所有文档,但最好是尽可能多地自动生成。

为了简化这一任务,ASP.NET Web API 提供一个库自动生成帮助页。

为 ASP.NET Web API 创建帮助页面(转载)

创建 API 帮助页

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

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

为 ASP.NET Web API 创建帮助页面(转载)

当您运行该应用程序时,主页页面包含 API 的帮助页面的链接。从主页上,相对路径是 /Help。

为 ASP.NET Web API 创建帮助页面(转载)

此链接为您带到 API 的摘要页。

为 ASP.NET Web API 创建帮助页面(转载)

此页的 MVC 视图是在 Areas/HelpPage/Views/Help/Index.cshtml 中定义的。您可以编辑此页后,可以修改布局、 介绍、 标题、 样式和等等。

该页面的主要部分是一个table布局的控制器的Api。使用IApiExplorer接口条目是动态生成的。(我会稍后再谈谈此接口)。如果您添加一个新的 API 控制器,在运行时自动更新的界面。

"API"列列出了 HTTP 方法和相对 URI。"说明"列中包含每个 API 的文档。最初,该文档是只是占位符文本。在接下来的部分中,我将展示如何从 XML 注释添加文档。

每个 API 已链接到一个网页提供更详细信息,包括示例请求和响应的代码。

为 ASP.NET Web 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 文档。在解决方案资源管理器中,右键单击该项目并选择属性。选择生成的页面。

为 ASP.NET Web API 创建帮助页面(转载)

根据输出,请检查XML 文档文件。在编辑框中,键入"App_Data/XmlDocument.xml"。

为 ASP.NET Web API 创建帮助页面(转载)

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

为 ASP.NET Web 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 的文档字符串。它将它们存储在文档属性中的ApiDescriptionApiParameterDescription的对象。