Web Api帮助页面或用户手册
2016-07-12 22:53
281 查看
我这么玩Web Api(一):帮助页面或用户手册(Microsoft and Swashbuckle Help Page)
组件添加完后,会自动生成帮助页面,文件存在区域(Areas)中
2.注册区域(Areas)
在Global.asax文件中的Application_Start()方法添加以下代码:
AreaRegistration.RegisterAllAreas();
浏览生成的帮助页面:http://localhost:xxxx/help
Web API的方法列表已经显示出来了,但是方法的描述还是默认的描述。
3. 修改配置文件生成位置
右键项目属性,指定输出xml。
修改Areas\HelpPage\App_Start\HelpPageConfig.cs中register方法里指定的xml路径为上述指定输出的路径。
再查看帮助页面,方法描述已经和代码注释一致。
注:这里可根据需要把Area中对应页面的英文词条更新成中文,当然样式也可以调整。
4.添加测试工具
在Nuget添加Test Client组件。
在Areas\HelpPage\Views\Help\Api.cshtml添加以下代码:
@Html.DisplayForModel("TestClientDialogs")
@section Scripts {
<link type="text/css" href="~/Areas/HelpPage/HelpPage.css" rel="stylesheet" />
@Html.DisplayForModel("TestClientReferences")
}
再次运行Help Page,每个API说明页面的右下角会多一个测试的按钮。
4.参考
http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages
然后就可以浏览生成的帮助页面:http://localhost:xxxx/swagger
Web API的方法列表已经显示出来了,但是方法的描述还没有显示出来。
2. 修改配置文件生成位置
右键项目属性,指定输出xml。
找到SwaggerConfig.cs
把 c.IncludeXmlComments(GetXmlCommentsPath())的注释去掉
实现GetXmlCommentsPath()方法,指定xml路径为上述指定输出的路径。
再查看帮助页面,方法描述已经和代码注释一致。
2. 常见异常
用Nuget引用dll的时候,它会在config中添加依赖项信息,但偶尔会没添加,这时会出现Could not load file or assembly 'XXX' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)异常。
此时只要在config中添加对应的依赖项就好
4.帮助页面词条及样式调整
如果要修改或编辑Swashbuckle Help Page的样式或词条,需要编辑SwaggerConfig.cs,相对Microsoft Help Page可能要复杂一点(我只改过Microsoft的,没改过Swashbuckle的)。具体如何修改可参考:https://github.com/domaindrivendev/Swashbuckle
Microsoft Help Page搭建起来相对要麻烦一点点,但是样式和词条修改会方便一点,因此,比较适合作为外部接口调用使用文档。
分类: ASP.NET Web API
前言
你需要为客户编写Api调用手册?你需要测试你的Api接口?你需要和前端进行接口对接?那么这篇文章应该可以帮到你。本文将介绍创建Web Api 帮助文档页面的两种方式,Microsoft Help Page和Swashbuckle Help Page。编写RESTful的Web Api
View CodeMicrosoft Help Page
1.在Nuget添加Help Page组件。组件添加完后,会自动生成帮助页面,文件存在区域(Areas)中
2.注册区域(Areas)
在Global.asax文件中的Application_Start()方法添加以下代码:
AreaRegistration.RegisterAllAreas();
浏览生成的帮助页面:http://localhost:xxxx/help
Web API的方法列表已经显示出来了,但是方法的描述还是默认的描述。
3. 修改配置文件生成位置
右键项目属性,指定输出xml。
修改Areas\HelpPage\App_Start\HelpPageConfig.cs中register方法里指定的xml路径为上述指定输出的路径。
再查看帮助页面,方法描述已经和代码注释一致。
注:这里可根据需要把Area中对应页面的英文词条更新成中文,当然样式也可以调整。
4.添加测试工具
在Nuget添加Test Client组件。
在Areas\HelpPage\Views\Help\Api.cshtml添加以下代码:
@Html.DisplayForModel("TestClientDialogs")
@section Scripts {
<link type="text/css" href="~/Areas/HelpPage/HelpPage.css" rel="stylesheet" />
@Html.DisplayForModel("TestClientReferences")
}
再次运行Help Page,每个API说明页面的右下角会多一个测试的按钮。
4.参考
http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages
Swashbuckle Help Page
1.在Nuget添加Swashbuckle组件。然后就可以浏览生成的帮助页面:http://localhost:xxxx/swagger
Web API的方法列表已经显示出来了,但是方法的描述还没有显示出来。
2. 修改配置文件生成位置
右键项目属性,指定输出xml。
找到SwaggerConfig.cs
把 c.IncludeXmlComments(GetXmlCommentsPath())的注释去掉
实现GetXmlCommentsPath()方法,指定xml路径为上述指定输出的路径。
再查看帮助页面,方法描述已经和代码注释一致。
2. 常见异常
用Nuget引用dll的时候,它会在config中添加依赖项信息,但偶尔会没添加,这时会出现Could not load file or assembly 'XXX' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)异常。
此时只要在config中添加对应的依赖项就好
4.帮助页面词条及样式调整
如果要修改或编辑Swashbuckle Help Page的样式或词条,需要编辑SwaggerConfig.cs,相对Microsoft Help Page可能要复杂一点(我只改过Microsoft的,没改过Swashbuckle的)。具体如何修改可参考:https://github.com/domaindrivendev/Swashbuckle
简单总结
Swashbuckle Help Page搭建起来相对会比较简单,但是样式(自带swagger logo)和词条修改会较麻烦一点,因此,比较适合作为内部接口说明几接口调用测试。Microsoft Help Page搭建起来相对要麻烦一点点,但是样式和词条修改会方便一点,因此,比较适合作为外部接口调用使用文档。
源码下载
https://github.com/ErikXu/WebApi.HelpPage分类: ASP.NET Web API
相关文章推荐
- ps灵魂区域:图像模式
- 迭代器模式-c++实现
- js元素获取
- (4) ebj学习:ejb发布web service
- stm32寄存器版学习笔记07 ADC
- git merge命令
- CentOS正确关机方法
- ECSHOP如何解决Deprecated: preg_replace()报错
- 更新被拒绝,因为您当前分支的最新提交落后于其对应的远程分支
- 优雅编程之这样取名字,你就"正常"了!
- 理解Angular中的$apply()以及$digest()
- Hive JDBC运行连接注意事项
- 【Qt】2.1 创建对话框
- Linux MySQL
- 图解Linux命令之--more命令
- 重启Tomcat后还是登录状态
- Android 设置dialog背景全透明无边框
- Oracle练习题
- java的pattern类和matcher类的使用详解
- java的pattern类和matcher类的使用详解