WebApi中帮助页Description的中文显示
2015-10-28 15:24
246 查看
转自:http://edi.wang/post/2013/10/28/auto-generate-help-document-aspnet-webapi
我选择Web API的一个重要原因就是因为可以自动生成文档,省去了开发人猿不少宝贵的时间。以前在用Web API第一代的时候,自动生成帮助文档的功能默认是不完整的,现在到了Web API 2,这个功能已经通过NuGet包的形式很好的整合到了一起。我们来看一下吧!
首先,用VS2013创建的Web API 2项目会默认带有Microsoft ASP.NET Web API Help Page的包。如果没有,就需要手动去NuGet上安装。
在安装了这个包以后,你的Web API项目目录里会多一个Area,里面有个HelpPage文件夹,这里面放的都是HelpPage生成器的代码、页面模版和配置文件。
在不做任何更改的情况下,你的WebAPI项目现在就已经具有基本的生成文档的功能了。
浏览/Help,即Areas.HelpPage.Controllers.HelpController的Index() Action,就能看到自动生成的API文档:
你们可能注意到,我的表格里“Description”字段是有内容的,而你们自己的是木有的。这个其实是需要额外去配置的。
这个Description的内容所使用的其实是代码里方法的注释,即/// <summary>形式的注释。如果你有撸过类库的经验,你会知道这些东西是可以生成XML的,许多文档生成器都要使用这份XML作为metadata的来源。
在我们的网站里,这样的metadata信息通常应该放在App_Data文件夹里,而不是默认的bin目录里。所以我们要对Web API的项目属性做一些更改。
打开项目属性,在Build页面里,勾选XML documentation file,并把他它撸到App_Data下面:
然后打开Areas\HelpPage\App_Start下的HelpPageConfig.cs
取消Register方法中第一段代码的注释,并且把XML文件的路径改成刚才在刚才在项目属性页里设置的路径。
现在,如果你在API方法上写三斜杠的注释,就会被生成在网页上。
我选择Web API的一个重要原因就是因为可以自动生成文档,省去了开发人猿不少宝贵的时间。以前在用Web API第一代的时候,自动生成帮助文档的功能默认是不完整的,现在到了Web API 2,这个功能已经通过NuGet包的形式很好的整合到了一起。我们来看一下吧!
首先,用VS2013创建的Web API 2项目会默认带有Microsoft ASP.NET Web API Help Page的包。如果没有,就需要手动去NuGet上安装。
在安装了这个包以后,你的Web API项目目录里会多一个Area,里面有个HelpPage文件夹,这里面放的都是HelpPage生成器的代码、页面模版和配置文件。
在不做任何更改的情况下,你的WebAPI项目现在就已经具有基本的生成文档的功能了。
浏览/Help,即Areas.HelpPage.Controllers.HelpController的Index() Action,就能看到自动生成的API文档:
你们可能注意到,我的表格里“Description”字段是有内容的,而你们自己的是木有的。这个其实是需要额外去配置的。
这个Description的内容所使用的其实是代码里方法的注释,即/// <summary>形式的注释。如果你有撸过类库的经验,你会知道这些东西是可以生成XML的,许多文档生成器都要使用这份XML作为metadata的来源。
在我们的网站里,这样的metadata信息通常应该放在App_Data文件夹里,而不是默认的bin目录里。所以我们要对Web API的项目属性做一些更改。
打开项目属性,在Build页面里,勾选XML documentation file,并把他它撸到App_Data下面:
然后打开Areas\HelpPage\App_Start下的HelpPageConfig.cs
取消Register方法中第一段代码的注释,并且把XML文件的路径改成刚才在刚才在项目属性页里设置的路径。
public static void Register(HttpConfiguration config) { // Uncomment the following to use the documentation from XML documentation file. config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/PatientView.Service.WebAPI.xml"))); ... }
现在,如果你在API方法上写三斜杠的注释,就会被生成在网页上。
相关文章推荐
- 我的电磁学讲义9:磁简史 磁的基本现象 安培定律
- VSFTPD实现基于虚拟用户的认证
- 流媒体技术:VS2012下RTP开源协议库JRTPLIB 3.9.1编译
- Goldengate 维护
- php将数组存储为文本文件方法汇总
- hdu 1255 覆盖的面积
- mysql 的定时sql任务
- IOS第三方字体
- 如何实现进程池
- LAMP
- mysql查看session连接数和session状态
- Progressbar 实例
- 多个按钮,点击单个按钮更改被点击按钮图片的方法
- 图片编辑,涂鸦。仿qq截图
- rtx 导出所有部门和用户
- 排序算法
- 集成百度地图
- 静态页编写标准及要求
- 日常收集整理php正则表达式(超常用)
- HTTPS的工作原理