转载地址: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 的文档字符串。它将它们存储在文档属性中的ApiDescriptionApiParameterDescription的对象。

最新文章

  1. Smart3D系列教程5之 《案例实战演练2——大区域的地形三维重建》
  2. UVM的类库
  3. python 调用 shell 命令方法
  4. Bootstrap-分页插件Paginator
  5. 经典的SQL语句面试题
  6. Oracle 补丁及opatch 工具介绍
  7. return_url和notify_url的区别
  8. MIT 计算机科学及编程导论 Python 笔记 1
  9. [转帖]NotePad++编辑Linux中的文件
  10. Python flask+react+antd实现登陆demo
  11. VMware vCenter Server 6.5配置群集功能
  12. [LeetCode] 577. Employee Bonus_Easy tag: SQL
  13. 配置ssh的config文件-为每个ssh连接创建别名
  14. Nlog、elasticsearch、Kibana以及logstash在项目中的应用(二)
  15. 移动端 输入框 如果类型是number,用户也可以输入汉字和字母
  16. Linux学习5-初学者注意事项
  17. Hadoop HBase概念学习系列之优秀行键设计(十六)
  18. Chrome-Adobe Flash 无法正常使用
  19. mysql数据库基本知识
  20. Java中的 toString 方法

热门文章

  1. win32 disk imager使用后u盘容量恢复
  2. mysql 主从复制实现步骤
  3. __getattribute__
  4. Eclipse工作空间相关操作
  5. ESB 客户端调用 处理类
  6. [AngularJS] New in Angular 1.3 - bindToController
  7. .Net高级技术
  8. .NET代码编写规范 整理
  9. opensuse13.1 双屏幕扩展
  10. phpMemcache消息队列类
  11. HDU5406---CRB and Apple( DP) 2015 Multi-University Training Contest 10
  12. 对css盒模型的理解
  13. Docker系列05—Docker 存储卷详解
  14. C#访问gsoap的服务--可用
  15. gentoo emacs 中文输入法 呼出
  16. maven遇到的一些问题
  17. ES6知识整理(10)--class的继承
  18. Valid Parentheses - LeetCode
  19. [Backbone] Working with forms
  20. 4种用于构建嵌入式linux系统的工具_转