有了swagger2,您就不必再担心API文档了

前端和后端的分离不会造成伤害

目前在互联网技术发展领域,前端与后端分离的开发模式似乎已成为主流模式。通常,后端工程师只需要制作API接口就可以向前端提供数据,而前端开发工程师则负责从后端请求数据并呈现页面。

这样做的好处是后端开发者只需要关注后端业务,前端开发者只需要关注前端业务;工作职责更加明确,开发效率大大提高。

在这个时候就出现了一个问题,前后端分离后数据交互的问题,前端开发工程师在去调用后端接口获取数据的时候,是要遵循一定的规则的,比如:传递给后端的参数类型等。这个规则就是我们常说的接口文档,这个文档就定义了前后端数据交互时的规范。

       作为一名程序猿,都或多或少地被接口文档折磨过,前端工程师经常抱怨后端给的接口文档与实际情况不一致;后端工程师总觉得太多的接口文档要编写以及维护接口文档会耗费不少精力,经常来不及更新。

       理想的状态应该是,编写好的接口文档同时发给前端和后端工程师,大伙按照既定的规则各自开发就OK了。

       而实际的工作中是经常充满着变化。然而,理想终归是理想。就像每个程序猿都会吐槽别的程序猿为什么总是不写注释,而自己在写代码的时候又总是很讨厌些注释一样。

       个爱动脑、爱思考、技术特别高超的程序猿群体,但凡我们在工作遇到不爽的问题,我们一定会利用我们“聪明绝顶”的大脑来把它搞定。今天我们就来说一个可以提高我们接口文档开发效率的工具swagger2。它的出现就是为了解决困扰程序猿的复杂的、难以维护的API接口的问题。

swagger2是什么?

A Powerful Interface to your API

       swagger2 是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful 风格的Web 服务。它主要包含三部分:

  • swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档,同时也能生成多钟语言的服务端和客户端的代码。

  • swagger UI:提供了一个可视化的UI页面展示描述文件。可以做一些的接口请求。

  • swagger Editor: 编辑swagger描述文件的编辑器,该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

SpringBoot整合swagger2

开始之前呢,按照惯例,先介绍一下开发环境:

  • Spring Boot 2.1.5

  • JDK 8

  • swagger 2.9.2

    接下来咱么就在项目中体验一下swagger2,首先我们使用 Intelli IDEA先通过Spring Initializr 创建一个基础的SpringBoot 项目。并且添加web的依赖,因为我们是RESTful风格的API。

添加swagger配置类

swagger提供了一个Docket 对象,我们可以灵活的配置swagger 的各项属性

配置实体类

@ApiModel 设置接口相关实体的描述

创建Controller

通过在控制器类上增加@Api注解,给控制器增加描述和标签信息。

*@Api: 可设置对控制器的描述。

测试

接口测试

点开查找用户接口,点击Tryit out,

输入用户id,然后点击Execute

测试结果

这样几步我们就完成了,SpringBoot整合swagger2的案例,相信大家都已经能够体会到swagger2对于程序员们的的便捷,赶紧动手实战吧。

到这里我们swagger2的内容就搞定了,恭喜你有Get了一个新技能。

END

//课工场大数据专场直播预告//

(惊喜好礼直播继续送)
开始时间:8月10日20:00

神秘一线 大咖亲临

为你带来别开生面的大数据盛宴
课工场3年磨一剑
北美专家、行业大咖、教学牛人

三点一线为你铺就大数据坦途
一起来聊一聊,大数据的“教”与“学”

我们不惧被模仿
因为我们始终无人能超越

扫描下方二维码

马上预约课工场大数据论坛专场

我们在直播间等你来!

资源下载: