SpringBoot - Swagger2的集成与使用教程(生成API接口文档)
在前后端分离开发中,为了减少与其它团队的沟通成本,一般都会构建一份 RESTful API 文档来描述所有的接口信息。但传统的方式有许多弊端,不仅编写文档工作量巨大,而且维护不方便,测试也不方便(需要借助第三方工具,如 Postman 来测试)
为解决这些问题,我们可以使用 Swagger 2 来构建在线接口文档,下面通过样例进行演示。
一、基本介绍
1,什么是 Swagger 2
Swagger 2 是一个开源软件框架,可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务,它将代码和文档融为一体,可以完美解决文档编写繁琐、维护不方便等问题。使得开发人员可以将大部分精力集中到业务中,而不是繁杂琐碎的文档中。
2,安装配置
(1)首先编辑项目的 pom.xml 文件,添加 Swagger 2 相关依赖:
注意:因为我这里引入的 swagger ui 是 2.7 以上的版本,所以还需要引入 guava,否则会因为 guava 兼容性问题造成项目启动报错(无法启动)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
(2)接着创建 Swagger 2 的配置类,代码如下: 代码说明:
- 首先通过 @EnableSwagger2 注解开启了 Swagger 2,然后最主要的是配置一个 Docket。
- 通过 apis 方法配置要扫描的 controller 位置,通过 paths 方法配置路径。
- 在 apiInfo 中构建文档的基本信息,例如描述、联系人信息、版本、标题等。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
二、使用样例
1,添加注解
(1)首先我们在 Controller 上添加相关的 @Api 注解:
(1)@Api 注解标注在类上用来描述整个 Controller 信息。
(2)@ApiOperation 注解标注在方法上,用来描述一个方法的基本信息。
(3)@ApiImplicitParam 注解标注在方法上,用来描述方法的参数。其中 paramType 是指方法参数的类型,有如下可选值:
- path:参数获取方式为 @PathVariable
- query:参数获取方式为 @RequestParam
- header:参数获取方式为 @RequestHeader
- body
- form
(4)如果有多个参数,可以将多个参数的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中。
(5)@ApiResponse 是对响应结果的描述。code 表示响应码,message 为相应的描述信息。如果有多个 @ApiResponse,则放在一个 @ApiResponses 中。
(6)@ApiIgnore 注解表示不对某个接口生成文档。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
|
(2)接着对模型对象也添加相关的注解:
由于在上面 Controller 里的 updateUser 方法中,使用 @RequestBody 注解来接收数据,此时可以通过 @ApiModel 注解和 @ApiModelProperty 注解配置 User 对象的描述信息。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
2,查看接口文档
(1)启动 Spring Boot 项目,在浏览器中输入 http://localhost:8080/swagger-ui.html 即可看到接口文档。
(2)展开任意一个接口描述,单击 Try it out 按钮后,可以实现对该接口的测试。
附:使用 swagger-bootstrap-ui 代替原来的 ui
(1)如果觉得原先使用的 swagger ui 比较丑、或者不方便的话,可以试试 swagger-bootstrap-ui。只需修改 pom.xml 文件,将原来的 springfox-swagger-ui 依赖替换成 swagger-bootstrap-ui 即可。
注意:1.9.6 是 swagger-bootstrap-ui 的最后一个版本。由于各种原因,原作者又另起一新的项目:knife4j-spring-ui。knife4j 会包含 swagger-bootstrap-ui 的所有特性,并增加许多新特性,有兴趣的小伙伴可以尝试一下。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
(2)项目启动后,通过 http://localhost:8080/doc.html 地址即可访问新的 UI 界面:
(3)可以看到 bootstrap 风格的界面样式比原先的清爽、高效许多: