如何使 WebAPI 自动生成漂亮又实用在线API文档
2017-01-20 08:54
561 查看
1.前言
1.1 SwaggerUI
SwaggerUI 是一个简单的Restful API 测试和文档工具。简单、漂亮、易用(官方demo)。通过读取JSON 配置显示API. 项目本身仅仅也只依赖一些 html,css.js静态文件. 你可以几乎放在任何Web容器上使用。1.2 Swashbuckle
Swashbuckle 是.NET类库,可以将WebAPI所有开放的控制器方法生成对应SwaggerUI的JSON配置。再通过SwaggerUI 显示出来。类库中已经包含SwaggerUI 。所以不需要额外安装。2.快速开始
创建项目 OnlineAPI来封装百度音乐服务(示例下载) ,通过API可以搜索、获取音乐的信息和播放连接。我尽量删除一些我们demo中不会用到的一些文件,使其看上去比较简洁。
WebAPI 安装 Swashbuckle
Install-Package Swashbuckle
代码注释生成文档说明。
Swashbuckle 是通过生成的XML文件来读取注释的,生成 SwaggerUI,JSON 配置中的说明的。
安装时会在项目目录 App_Start 文件夹下生成一个 SwaggerConfig.cs 配置文件,用于配置 SwaggerUI 相关展示行为的。如图:
将配置文件大概99行注释去掉并修改为
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
并在当前类中添加一个方法
/// ///
/// ///protected static string GetXmlCommentsPath(string name){ return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name); }
紧接着你在此Web项目属性生成选卡中勾选 “XML 文档文件”,编译过程中生成类库的注释文件
添加百度音乐 3个API
访问
http:///swagger/ui/index,最终显示效果
我们通过API 测试API 是否成功运行
3.添加自定义HTTP Header
在开发移动端 API时常常需要验证权限,验证参数放在Http请求头中是再好不过了。WebAPI配合过滤器验证权限即可首先我们需要创建一个 IOperationFilter 接口的类。IOperationFilter
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter();
添加Web权限过滤器
在你想要的ApiController 或者是 Action 添加过滤器
[AccessKey]
最终显示效果
4.显示上传文件参数
SwaggerUI 有上传文件的功能和添加自定义HTTP Header 做法类似,只是我们通过特殊的设置来标示API具有上传文件的功能在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter();
API 文档展示效果
5.版本和资源
你可以通过下列连接获取相关说明。OnlineAPI Demo 项目下载
OnlineAPI Demo下载
Swashbuckle 项目地址: https://github.com/domaindrivendev/Swashbuckle swagger-ui 项目地址: https://github.com/swagger-api/swagger-ui swagger-ui 官网地址: http://swagger.io/swagger-ui/
相关文章:
WebAPI前置知识:HTTP与RestfulAPI
WEB API系列(一):WEB API的适用场景、第一个实例
WEB API 系列(二) Filter的使用以及执行顺序
ASP.NET Web API 安全筛选器
Web API 基于ASP.NET Identity的Basic Authentication
ASP.NET Web Api使用CacheCow和ETag缓存资源
使用 West Wind WebSurge 对 ASP.NET Web API 服务进行压力测试
Web API应用支持HTTPS的经验总结
Dion Hinchcliffe谈Web API的过去与未来
WebAPI生成可导入到PostMan的数据
原文地址:http://www.cnblogs.com/Arrays/p/5146194.html
.NET社区新闻,深度好文,微信中搜索dotNET跨平台或扫描二维码关注
相关文章推荐
- Swashbuckle 如何使 WebAPI 自动生成漂亮又实用在线API文档[转]
- 如何使 WebAPI 自动生成漂亮又实用在线API文档
- 如何使 WebAPI 自动生成漂亮又实用在线API文档
- 如何使 WebAPI 自动生成漂亮又实用在线API文档
- 如何开发一个java开源框架-----Jvn框架之实现自动生成在线文档(第七讲)
- 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)
- (转)WebApi自动生成在线文档Swashbuckle
- (转)WebApi自动生成在线文档WebApiTestClient
- 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)
- (转)WebApi自动生成在线文档Swashbuckle
- swagger:API在线文档自动生成框架
- Spring Boot如何让Web API自动生成文档,并解决swagger-annotations的API注解description属性废弃的问题
- 使用swagger实现在线api文档自动生成 在线测试api接口
- jsdoc注释规范工具(使用 JSDoc 3 自动生成 JavaScript API 文档)
- 如何在线生成Word文档?一种极简,极强大的方法,支持图片表格等各种格式
- app后端开发二:API接口文档自动生成工具
- webAPI 自动生成帮助文档
- 如何试用eclipse 生成API帮助文档?
- 自动生成api文档
- vs2010代码注释自动生成api文档(Sandcastle帮助文档生成器使用介绍)