在前后端分离开发中，为了减少与其它团队的沟通成本，一般都会构建一份 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
- 首先通过 @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
由于在上面 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 按钮后，可以实现对该接口的测试。
（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
（3）可以看到 bootstrap 风格的界面样式比原先的清爽、高效许多：
版权声明：
本文来源网络，所有图片文章版权属于原作者，如有侵权，联系删除。
本文网址：https://www.mushiming.com/mjsbk/15260.html