很多开发人员都不喜欢写文档! 在他们根深蒂固的观念中, 写文档就是浪费时间, 还不如直接写代码酣畅淋漓的痛快! 尤其是对于 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 文档进行管理, 是个不错的选择.
来源: http://www.jianshu.com/p/190e7bf764a9