当你创建一个网络 API 时,它很有用来创建一个帮助页,以便其他开发人员将知道如何调用您的 API。您可以创建的所有文档手动,但它是自动生成尽可能多地更好。

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

1.创建 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有一个链接页面,提供更加详细的信息。包括请求体和响应体的示例。

2.将帮助页添加到现有的项目

你可以在一个已经存在的项目通过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视图创建链接,请添加以下内容:

 @Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

当然,也需要注册区域路由规则。

在Global.asax文件,在Application_Start方法添加以下代码,如果这不存在的话:

 protected void Application_Start()
{
// Add this code, if not present.
AreaRegistration.RegisterAllAreas();
// ...
}

3.添加Api文档

默认情况下,这个帮助页面由documentation去替换占位的文本,你也可以使用XML文档注释去创建documentation。

如果你要启用这个功能,你需要打开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的控制器/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";
}

提示:如果你的方法上方有三个斜杠,VS将自动插入XML的元素。

现在生成项目并且再次运行应用程序,并导航到帮助页。这些注释字符串应该会在Api的表格上显示。

这个帮助页就会从XML文件读取字符串,当你部署应用程序的时候,请确保XML文件是存在的。

4.Under the Hood

这些帮助页都是简历在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 的文档字符串。它将它们存储在文档属性中的ApiDescriptionApiParameterDescription的对象。

 

1.3为WebApi创建帮助文档的更多相关文章

  1. ABBYY PDF Transformer+从文件选项中创建PDF文档的教程

    可使用OCR文字识别软件ABBYY PDF Transformer+从Microsoft Word.Microsoft Excel.Microsoft PowerPoint.HTML.RTF.Micr ...

  2. C#实现通过模板自动创建Word文档的方法

    原文地址:http://www.jb51.net/article/55332.htm   本文实例讲述了C#实现通过模板自动创建Word文档的方法,是非常实用的技巧.分享给大家供大家参考.具体实现方法 ...

  3. 在C#中创建word文档

    在下面文档中  首先引用word组件:Microsoft.Office.Interop.Word 在头文件中写上 using Word = Microsoft.Office.Interop.Word; ...

  4. C#程序通过模板自动创建Word文档

    引言:前段时间有项目要用c#生成Word格式的计算报告,通过网络查找到很多内容,但是都很凌乱,于是自己决定将具体的步骤总结整理出来,以便于更好的交流和以后相似问题可以迅速的解决! 现通过具体的示例演示 ...

  5. C# 创建XML文档

    有些时候我们需要生成一个xml文档作为数据交换的容器.当然我们用拼接字符串的方法来进行构建xml,但是这种方法虽然简单有效,但是如果xml文档结构过于复杂,拼接字符串会让人眼花缭乱.这时候就需要C#给 ...

  6. .net快速创建PDF文档 by c#

    原文地址:http://www.cnblogs.com/Creator/archive/2010/03/13/1685020.html C#引用IText创建PDF文档 先引用IText    可以从 ...

  7. Java 后台创建word 文档

    ---恢复内容开始--- Java 后台创建 word 文档 自己总结  网上查阅的文档 分享POI 教程地址:http://www.tuicool.com/articles/emqaEf6 方式一. ...

  8. lucene全文搜索之三:生成索引字段,创建索引文档(给索引字段加权)基于lucene5.5.3

    前言:上一章中我们已经实现了索引器的创建,但是我们没有索引文档,本章将会讲解如何生成字段.创建索引文档,给字段加权以及保存文档到索引器目录 luncene5.5.3集合jar包下载地址:http:// ...

  9. 使用LINQ TO XML 创建xml文档,以及读取xml文档把内容显示到GridView例子

    首先,准备了一个Model类 using System; using System.Collections.Generic; using System.Linq; using System.Text; ...

随机推荐

  1. java程序设计之反弹高度

    题目:一球从100米高度自由落下,每次落地后反跳回原高度的一半:再落下,求它在第10次落地时,共经过多少米?第10次反弹多高? 代码: public class highe { double high ...

  2. Revolving Digits[EXKMP]

    Revolving Digits Time Limit: 3000/1000 MS (Java/Others)    Memory Limit: 65536/32768 K (Java/Others) ...

  3. node基础11:接受参数

    1.接收参数 在Node中接受GET/POST请求的参数不像PHP那样,在PHP中直接有全局变量$_GET,$_POST来接受url,或者请求体重的参数. 在node中接受GET参数使用url.par ...

  4. Query节点操作,jQuery插入节点,jQuery删除节点,jQuery Dom操作

    一.创建节点 var box = $('<div>节点</div>'); //创建一个节点,或者var box = "<div>节点</div> ...

  5. Linux 中 Nginx 重启关闭

    如果服务器正在运行的 Nginx 要进行升级.添加或删除模块时. 我们需要停掉服务器并做相应修改,这样服务器就要在一段时间内停止服务. Nginx可以在不停机的情况下进行各种升级动作而不影响服务器运行 ...

  6. 基于Bootstrap仿淘宝分页控件实现

    .header { cursor: pointer } p { margin: 3px 6px } th { background: lightblue; width: 20% } table { t ...

  7. [转]iostat命令详解

    iostat iostat用于输出CPU和磁盘I/O相关的统计信息.  命令格式: iostat [ -c | -d ] [ -k | -m ] [ -t ] [ -V ] [ -x ] [ devi ...

  8. datatable刷新表头

    使用jQuery的datatable生成表格数据,当需要改变表头时,调用Table.fnDestroy();再重新创建表头 var oTable = null; function initSettin ...

  9. 递推 hdu 2048

    t 关于错排 共n个数 第n个 和一个交换  其他n-2错排  (n-1)*z[n-2]; n-1个错排 第n个和n-1个交换    (n-1)*z[n-1]; 求和 然后概率的话要除n! 一个一个除 ...

  10. ajax 多个表单值问题,表单序列化加其它表单值

    $.ajax({ type: "post", url: "{:u('cart/totalByCard')}?t="+Math.random(9999), dat ...