定制高端伴游网

长期更新最新认证伴游服务

随缘伴游网 首页 伴游资讯 国内新闻 查看内容

Spring Boot 2.x使用Swagger2构建强大的API文档(一)

2020-4-3 23:46| 发布者: 伴游网新闻发布| 查看: 380| 评论: 0

摘要: 前言随着前后端分离架构和微服务架构的流行,我们使用Spring Boot来构建RESTful API项目的场景越来越多。通常我们的一个RESTful API就有可能要服务于多个不同的开发人员或开发团队:IOS开发、Android开发、Web开发甚

前言

随着前后端分离架构和微服务架构的流行,我们使用Spring Boot来构建RESTful API项目的场景越来越多。通常我们的一个RESTful API就有可能要服务于多个不同的开发人员或开发团队:IOS开发、Android开发、Web开发甚至其他的后端服务等。

相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新

其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。

解决方案

为了解决上面这样的问题,本文将介绍RESTful API的重磅好伙伴Swagger2,它可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示:

Spring Boot 2.x使用Swagger2构建强大的API文档(一)


基于Spring框架的Swagger流程应用

这里暂不会介绍Swagger的工具具体如何使用,不会讲yml或者json格式描述文件的语法规范,也不会讲如何在SpringMVC或者Spring Boot中配置Springfox-swagger。这些都能从网上找到,而且配置起来都非常的简单。

这里想讲的是如何结合现有的工具和功能,设计一个流程,去保证一个项目从开始开发到后面持续迭代的时候,以最小代价去维护代码、接口文档以及Swagger描述文件

项目开始阶段

一般来说,接口文档都是由服务端来编写的。在项目开发阶段的时候,服务端开发可以视情况来决定是直接编写服务端调用层代码,还是写Swagger描述文件

建议是如果项目启动阶段,就已经搭好了后台框架,那可以直接编写服务端被调用层的代码(即controller及其入参出参对象),然后通过Springfox-swagger 生成swagger json描述文件。

如果项目启动阶段并没有相关后台框架,而前端对接口文档追得紧,那就建议先编写swagger描述文件,通过该描述文件生成接口文档。后续后台框架搭好了,也可以生成相关的服务端代码。

项目迭代阶段

到这个阶段,事情就简单很多了。后续后台人员,无需关注Swagger描述文件和接口文档,有需求变更导致接口变化,直接写代码就好了。把调用层的代码做个修改,然后生成新的描述文件和接口文档后,给到前端即可。真正做到了一劳永逸。

推荐流程

Spring Boot 2.x使用Swagger2构建强大的API文档(一)

上面的流程就是在开发阶段,和我们的调用代码一起编写,一个调用接口编写时,根据此接口的功能因为,入参和出参就可以定下来,这个时候我们就可以编写swagger文档,然后在编写我们的实际代码。

有的时候我们需要把文档静态化,导出html或pdf,就可以利用maven插件去实现

给Mock系统的正常请求及响应全流程数据

很多时候,如果你能在提供接口文档的同时,把所有接口的模拟请求响应数据也提供给前端。或者有Mock系统,直接将这些模拟数据录入到Mock系统中,那将会提高前端的开发效率,减少许多发生在联调时候才会发生的问题

通过适当地在代码中加入swagger的注解,可以让你的接口文档描述信息更加详细,如果你把每个出入参数的示例值都配上,那前端就可以直接在接口文档中拿到模拟数据。


如下:

Spring Boot 2.x使用Swagger2构建强大的API文档(一)

Spring Boot 2.x使用Swagger2构建强大的API文档(一)

Spring Boot 2.x使用Swagger2构建强大的API文档(一)

通过example属性,可以模拟请求数据报文,如下

Spring Boot 2.x使用Swagger2构建强大的API文档(一)

上图是请求参数的案例。

Spring Boot 2.x使用Swagger2构建强大的API文档(一)

上图是返回值的案例,非常清晰,还有相关的案例数据。

总结

其实归根到底,使用Swagger,就是把相关的信息存储在它定义的描述文件里面(yml或json格式),再通过维护这个描述文件可以去更新接口文档,以及生成各端代码。

Springfox-swagger,则可以通过扫描代码去生成这个描述文件,连描述文件都不需要再去维护了。所有的信息,都在代码里面了。代码即接口文档,接口文档即代码。

Spring Boot 2.x使用Swagger2构建强大的API文档(一)


来源:https://www.toutiao.com/a6808773551483519496/
免责声明:如果侵犯了您的权益,请联系站长,我们会及时删除侵权内容,谢谢合作!

鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

相关分类

联系我们
随缘伴游网

客服QQ:

服务时间:周一到周日10:00-23:00

手机访问

Archiver手机版小黑屋随缘伴游网

Powered by suiyuan   © 2018-2028 syby9.com.