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.2，Spring Boot版本2.0.6 RELEASE。spring-boot-starter-web提供了Spring MVC的支持。如下图所示：

依赖项

第二步，编写启动类，在类上使用@SpringBootApplication和@EnableSwagger2注解，并使用@Bean注解实例化一个Docket的Bean。为方便开发使用，@SpringBootApplication内部是整合了@Configuration、@EnableAutoConfiguration和@ComponetScan注解，并开启了Spring Boot 程序的组件扫描和自动配置功能。其中，@Configuration是将Swagger2与Spring 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文档进行管理，是个不错的选择。