ASP.NET Web API 2:创建API帮助页面

 
     当你新建了一个web API服务之后,再建一个API帮助页面是很有好处的,这样其他开发人员就会很清楚地知道如何调用你的API接口。你可以选择自己手工建立,但是如果能自动生成岂不是更好。为了简化这项任务, ASP.NET Web API提供了一个在运行时自动生成帮助页的库。
 
 
在项目中添加帮助页,首先使用NuGet安装Microsoft.AspNet.WebApi.HelpPage库
 

安装成功后,启动项目有可能会报下图的异常
 
 
引起异常的原因是Microsoft.AspNet.WebApi.HelpPage库要依赖于如下程序集,如果项目中使用的程序集版本低于它依赖的版本,NuGet就会把这些程序集升级到依赖的版本。升级之后引起了本地程序集和GAC的程序集冲突。
解决该问题的办法是,在项目的Web.config配置文件中的runtime节点,添加:
< dependentAssembly>
< assemblyIdentity name = "System.Web.WebPages.Razor " publicKeyToken =" 31bf3856ad364e35 "/>
< bindingRedirect oldVersion = "1.0.0.0-3.0.0.0 " newVersion =" 3.0.0.0 "/>
</ dependentAssembly >

在项目Areas 文件夹下就自动生成了有关帮助页的所有代码文件

启动项目,帮助页的相对路径是/Help,如果你新增加了API控制器,帮助页内容会在运行时自动更新。
帮助页对应的MVC视图在项目中的路径是Areas/HelpPage/Views/Help/Index.cshtml,你可以随自己的意愿定制该视图的布局、介绍、标题、样式等等。
默认生成的帮助页有很多没什么实际意义的占位字符串。
你可以使用XML文档注释功能来创建有意义的文档。要开启该功能,需要打开Areas/HelpPage/App_Start/HelpPageConfig.cs文件,取消下面这句代码的注释:
// Uncomment the following to use the documentation from XML documentation file.
config.SetDocumentationProvider( new XmlDocumentationProvider ( HttpContext.Current.Server.MapPath( "~/App_Data/XmlDocument.xml" )));
然后在解决方案资源管理器,右键项目名称,选择属性,选择生成,在输出配置项,勾选XML文档文件,修改输出路径为App_Data/XmlDocument.xml
然后打开API控制器文件,通过XML文档注释方式(///方式)给控制器的Action方法添加注释
/// <summary>
/// 查询指定ID的商品信息
/// </summary>
/// <param name="id"> 商品ID </param>
/// <returns> 查询到的商品记录 </returns>
[ HttpGet]
public Product Get( int id)
{
return repository.Products.FirstOrDefault(p => p.ProductId == id);
}
重新编译运行项目,导航到帮助页,添加的注释信息就显示到了帮助页
如果要帮助页上隐藏某个API接口的信息,可以给该Action添加ApiExplorerSettings特性同时IgnoreApi属性设置为true
/// <summary>
/// 获取商品列表
/// </summary>
/// <returns> 商品列表 </returns>
[ ApiExplorerSettings(IgnoreApi = true )]
public IEnumerable < Product> Get()
{
return repository.Products;
}
你也可以给控制器添加该特性,整个控制器的信息都不会出现在帮助页上。
 
 
分类: WebAPI
标签: WebAPI

API帮助页面的更多相关文章

  1. Web Api帮助页面或用户手册

    我这么玩Web Api(一):帮助页面或用户手册(Microsoft and Swashbuckle Help Page)   前言 你需要为客户编写Api调用手册?你需要测试你的Api接口?你需要和 ...

  2. 如何使用Web3.js API 在页面中进行转账

    本文介绍如何使用Web3.js API 在页面中进行转账,是我翻译的文档Web3.js 0.2x 中文版 及 区块链全栈-以太坊DAPP开发实战 中Demo的文章说明. 写在前面 阅读本文前,你应该对 ...

  3. ASP.NET Web API 2:创建API帮助页面

         当你新建了一个web API服务之后,再建一个API帮助页面是很有好处的,这样其他开发人员就会很清楚地知道如何调用你的API接口.你可以选择自己手工建立,但是如果能自动生成岂不是更好.为了简 ...

  4. 通过HTML5 Visibility API检测页面活动状态

    几年前,我们浏览网页的时候是没有选项卡浏览模式的,每一个网页都会是一个浏览器窗口,如果我没有记错,Win7之前我们都是这样浏览网页的.作为一个程序员,我们经常会同时打开10-15个网页,多的时候超过2 ...

  5. bootshiro---开源的后台管理框架--基于springboot2+ shiro+jwt的真正rest api资源无状态认证权限管理框架,开发人员无需关注权限问题,后端开发完api,前端页面配置即可

    https://gitee.com/tomsun28/bootshiro

  6. 我这么玩Web Api(一):帮助页面或用户手册(Microsoft and Swashbuckle Help Page)

    前言 你需要为客户编写Api调用手册?你需要测试你的Api接口?你需要和前端进行接口对接?那么这篇文章应该可以帮到你.本文将介绍创建Web Api 帮助文档页面的两种方式,Microsoft Help ...

  7. 杂谈:HTML 5页面可视性API

    译文来源:http://www.ido321.com/1126.html 原文:HTML5 Page Visibility API 译文:HTML 5的页面可视性API 译者:dwqs 在早期,浏览器 ...

  8. 【ASP.NET Web API教程】2.4 创建Web API的帮助页面

    原文:[ASP.NET Web API教程]2.4 创建Web API的帮助页面 注:本文是[ASP.NET Web API系列教程]的一部分,如果您是第一次看本博客文章,请先看前面的内容. 2.4 ...

  9. 【ASP.NET Web API教程】2.4 创建Web API的帮助页面[转]

    注:本文是[ASP.NET Web API系列教程]的一部分,如果您是第一次看本博客文章,请先看前面的内容. 2.4 Creating a Help Page for a Web API2.4 创建W ...

随机推荐

  1. 算法 - 乞讨n中位数(C++)

    //************************************************************************************************** ...

  2. HTML5 CSS3 精美案例 : 达到VCD盒个性幻灯片

    转载请注明出处:http://blog.csdn.net/lmj623565791/article/details/31015121 哈,首先感谢下w3cfuns教师,行~ 行.这一次分享发夹CSS3 ...

  3. CreateEvent、SetEvent、ResetEvent和WaitForSingleObject

    事件对象就像一个开关:它仅仅有两种状态---开和关.当一个事件处于"开"状态.我们称其为"有信号".否则称为"无信号". 能够在一个线程的运 ...

  4. vijos 1234 口袋的天空

    最小生成树kruscal算法 #include<iostream> #include<algorithm> #include<cstring> #define ma ...

  5. CVE-2014-4113:飓风熊猫(HURRICANE PANDA)Win64bit提起权0day破绽

    飓风熊猫被觉得是原产于中国.主要针对基础设施公司的先进攻击者.我们知道它们除了拥有0day漏洞外.还有其它的三种本地特权提升漏洞.我们知道飓风熊猫使用的是"ChinaChopper" ...

  6. [WebGL入门]四,渲染准备

    注意:文章翻译http://wgld.org/,原作者杉本雅広(doxas),文章中假设有我的额外说明,我会加上[lufy:].另外.鄙人webgl研究还不够深入,一些专业词语,假设翻译有误,欢迎大家 ...

  7. 使用Visual Studio 2010写Data Url生成工具C#版本

    声明:本文系本人按照真实经历原创.未经许可,谢绝转载. 此文百度经验版本号:怎样用Visual Studio 2010打造Data Url生成工具 源代码下载:用Visual Studio 2010编 ...

  8. Run Book Automation - RBA系统介绍

    什么是RBA系统? 介绍这个系统之前, 先介绍一下开发这个系统的公司. BMC BMC软件公司是全球率先的业务服务管理解决方式的开发及供应商,现为全球第六大独立软件公司. 通过帮助用户主动提升服务.降 ...

  9. Javascript标准类型的方法集

    1 array.concat(item...) concat方法会产生一个新数组,将一个或多个item附加在数组之后 var a = ['a', 'b', 'c'] var b = ['x', 'y' ...

  10. 设计模式Template Method模式(Template Method)摘录

    23种子GOF设计模式一般分为三类:创建模式.结构模型.行为模式. 创建模式抽象的实例.怎样创建.组合和表示它的那些对象.一个类创建型模式使用继承改变被实例化的类,而一个对象创建型模式将实例化托付给还 ...