Spring Boot 2.0 集成Swagger2开发RESTful风格的Web服务

很多开发人员都不喜欢写文档!在他们根深蒂固的观念中,写文档就是浪费时间,还不如直接写代码酣畅淋漓的痛快!尤其是对于Java后台开发人员而言,维护一份接口文档,更是一件痛不欲生的事情!接口太多了,变化太多了,改完代码还要改文档。流程不规范的团队,经常会出现这样的情况:有时候接口代码变了,文档没有及时更新,前端开发人员不知道;有时候是后台开发人员直接与前端开发人员私下商量一致,直接更新代码不更新文档,久而久之,文档就是去了作用,成了摆设。另外,接口测试工作要借助类似Postman的第三方工具。但事与人违,文档是交流沟通的媒介,文档是项目验收的必备材料,文档是知识和经验的积累!每一个开发人员无法避免的一项工作,就是写文档!

那么,有没有什么工具能够帮助我们自动生成接口文档呢?懒人自有天助吧!Swagger帮助我们解决以上困惑。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。在Spring Boot项目中,可以将文件的方法、参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 作用主要包括两点:接口文档在线自动生成和功能测试。

下面,我们来详细介绍Spring Boot 2.0 集成 Swagger2 流程:

第一步,新建工程,在POM中添加Swagger2依赖,版本是2.9.2Spring Boot版本2.0.6 RELEASEspring-boot-starter-web提供了Spring MVC的支持。如下图所示:

依赖项

第二步,编写启动类,在类上使用@SpringBootApplication@EnableSwagger2注解,并使用@Bean注解实例化一个DocketBean。为方便开发使用,@SpringBootApplication内部是整合了@Configuration、@EnableAutoConfiguration@ComponetScan注解,并开启了Spring Boot 程序的组件扫描和自动配置功能。其中,@Configuration是将Swagger2Spring Boot项目进行整合的关键注解。

启动类

第三步,至此,Swagger2可以与Spring Boot项目一起工作了。运行项目,在浏览器中访问URL(localhost:8080/v2/api-docs),验证效果如下图所示:

运行结果

第四步,问题接踵而至。第三步访问URL运行结果是一堆JSON串,非常生涩难懂,不具有人性化。庆幸的是,Swagger2提供了UI交互的解决方案,在POM中添加Swagger2 UI 依赖。如下图:

依赖项

第五步, 运行项目,在浏览器中访问URL(localhost:8080/swagger-ui.html),验证效果如下图所示:

运行结果

第六步,新建SwaggerController类,提供RESTFul服务,如下图所示:

SwaggerController类

第七步,运行项目,在浏览器中访问URL(localhost:/swagger-ui.html),点击“Try it out!”按钮,可以进行服务接口测试。验证效果如下图所示:​

运行结果

结束语:综上所述,相比为接口编写文档的工作,我们增加的配置内容是非常少而且精简的,对于原有代码的影响也在忍受范围之内。因此,在构建RESTful API的同时,加入Swagger2来对API文档进行管理,是个不错的选择。

你可能感兴趣的:(Spring Boot 2.0 集成Swagger2开发RESTful风格的Web服务)