Swagger使用总结
2016-05-18 22:27
316 查看
Swagger使用总结
1. Swagger是什么?
官方说法:Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。个人觉得,swagger的一个最大的优点是能实时同步api与文档。在项目开发过程中,发生过多次:修改代码但是没有更新文档,前端还是按照老旧的文档进行开发,在联调过程中才发现问题的情况(当然依据开闭原则,对接口的修改是不允许的,但是在项目不稳定阶段,这种情况很难避免)。
2. spring boot 集成 Swagger
目前维护的系统是基于springboot框架开发的,因此本文会详细描述springboot与swagger集成的过程。spring-boot系统集成swagger需要进行如下操作:
添加maven依赖,需要在系统的pom中添加如下依赖:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency>
添加swagger配置文件,配置文件如下:
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() // 选择那些路径和api会生成document .apis(RequestHandlerSelectors.any()) // 对所有api进行监控 .paths(PathSelectors.any()) // 对所有路径进行监控 .build(); } }
通过注解EnableSwagger2声明Swagger的可用性,此处会定义一个类型为Docket的bean,
关于docket类的说明如下:
A builder which is intended to be the primary interface into the swagger-springmvc framework.Provides sensible defaults and convenience methods for configuration.
Docket的select()方法会提供给swagger-springmvc framework的一个默认构造器(ApiSelectorBuilder),这个构造器为配置swagger提供了一系列的默认属性和便利方法。
测试
通过访问:http://localhost:8080/your-app-root/v2/api-docs ,能测试生成的api是否可用。此时返回的是一个json形式的页面,可读性不好。可以通过Swagger UI来生成一个可读性良好的api页面。具体做法就是,在pom中添加相关依赖。如下:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency>
再次访问:http://localhost:8080/your-app-root/swagger-ui.html 就可以看到可读性较好的api文档页面。
注意:
http://localhost:8080/your-app-root/v2/api-docs 中your-app-root指的你的wabapp的根路径,我目前的webapp就默认在根路径下,所以地址是:http://localhost:8080/v2/api-docs
spring-mvc上引用swagger需要做其他相关的配置,具体请查看参考文献
swagger对restful风格的api支持的比较好,非restful风格的api支持的不是很好,对于非restful风格的api或者其他语言(非java语言)可以采用 http://editor.swagger 编辑器来收工完成相关的API编写
参考文献
swagger-2-documentation-for-spring-rest-api
相关文章推荐
- 即时通讯:第一阶段(登录和注册)
- Struts2间接访问Servlet API(ActionContex--一般推荐使用)
- GDOI2016 Day1 T1 中学生数学题
- POJ 1007(稳定排序)
- 电商系统的高并发设计和挑战
- 浅析ID与CLASS的区别
- 剑指Offer----面试题二:实现Singleton模式
- F8App-ReactNative项目源码分析1-初体验
- The internals of Python string interning
- 那些被漏掉的JQuery总结(三)——关于前台的数据计算问题
- 第一讲数据结构(2)
- NYOJ 88-汉诺塔(一)【罗汉塔定理f(x)=2*f(x-1)+1,快速幂模板】
- R语言 处理缺失值(二)
- AOP,OOP两种编程思想联系
- [数据库事务与锁]详解八:底理解数据库事务乐观锁的一种实现方式——CAS
- javaWeb开发之(一)_jdk安装与配置(Windows)
- Centos 7 NS 2.35安装
- 去某某-JAVA开发面试
- 设计模式总结篇系列:模板方法模式(Template Method)
- 第十一周项目2.1—存储班长信息的学生类