SpringBoot(十) Swagger2 - 基础

认识Swagger2

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

传统做法

我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:
(1)由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
(2)随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。

新潮做法

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

Swagger2示例 - Welcome

添加依赖

1
2
3
4
5
6
7
8
9
10
11
<!-- 添加Swagger2依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>

常用注解

注解 说明
@ApiOperation 给API增加说明
@ApiImplicitParams 给参数增加说明
@ApiImplicitParam 同上
@ModelAttribute 绑定参数
@PathVariable 获取uri参数绑定到函数的参数中

创建Swagger2配置类

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
45
46
47
48
49
/**
* @author Ray
* @date 2018/7/26 0026
* Swagger2的配置文件
*/
@Configuration
@EnableSwagger2
public class Swagger2Configuration {

// 是否开启swagger, 正式环境一般是需要关闭的, 可根据springboot的多环境配置进行设置
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;

/**
* 设置文档信息
*/
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
// 页面标题
.title("Springboot2 使用 Swagger2 示例")
// 描述
.description("个人博客: https://qq343509740.gitee.io/")
// 设置作者联系方式,可有可无
.contact("Ray")
// 版本号
.version("1.0")
.build();
}

/**
* 通过createRestApi函数创建Docket
* Swagger会扫描指定包下所有Controller定义的API,
* 并产生文档内容(除了被@ApiIgnore指定的请求)。
*/
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
// 是否开启 Swagger
.enable(swaggerEnabled)
// 创建该Api的基本信息(这些基本信息会展现在文档页面中)
.apiInfo(apiInfo())
// 返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,
.select()
// 扫描的路径包
.apis(RequestHandlerSelectors.basePackage("com.ray.springboot210.controller"))
.paths(PathSelectors.any())
.build();
}
}

通过@Configuration注解,让Spring来加载该类配置。
正式环境一般是需要关闭Swagger的, 可根据springboot的多环境配置进行设置

application.yml

1
2
3
# 开启 swagger
swagger:
enabled: true

访问Swagger2

enabled: true

访问地址: http://localhost:8080/swagger-ui.html

enabled: false

访问地址: http://localhost:8080/swagger-ui.html

Swagger2示例 - RESTful

User实体类

@ApiModelProperty 注解在实体对象中的属性上添加描述

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
/**
* @author Ray
* @date 2018/7/26 0026
* 用户实体类
* @ApiModelProperty 添加描述
*/
@Data
public class User implements Serializable {

private static final long serialVersionUID = -8899841606238605780L;

@ApiModelProperty(value = "用户编号", name = "id", example = "1", required = true)
private Long id;

@ApiModelProperty(value = "用户姓名", name = "name", example = "Ray")
private String name;

@ApiModelProperty(value = "用户年龄", name = "age", example = "18")
private Integer age;

/**
* 示例, 没有实际作用
*/
@ApiModelProperty(value = "状态数组", hidden = true)
private List<String> stateList;
}

controller控制层

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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
/**
* @author Ray
* @date 2018/7/26 0026
* 通过@ApiOperation注解来给API增加说明
* 通过@ApiImplicitParams@ApiImplicitParam注解来给参数增加说明
* 使用RESTful风格
*/
@Api(value = "UserController", description = "用户实体类控制器")
@RestController
@RequestMapping(value = "/users")
public class UserController {

/**
* 模拟CRUD操作
*/
private static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());

/**
* 处理 "/users/" 的GET请求, 用来获取用户列表
* 还可以通过@RequestParam从页面中传递参数来进行查询条件或者翻页信息的传递
*/
@ApiOperation(value = "用户列表", notes = "获取所有用户列表")
@GetMapping(value = "/")
public List<User> getUserList(){
List<User> list = new ArrayList<>(users.values());
return list;
}

/**
* 处理POST 请求, 用来创建用户
* 除了@ModelAttribute绑定参数之外,还可以通过@RequestParam从页面中传递参数
*/
@ApiOperation(value = "创建用户", notes = "根据User创建用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户编号(必填)", required = true),
@ApiImplicitParam(name = "name", value = "用户姓名"),
@ApiImplicitParam(name = "age", value = "用户年龄"),
})
@PostMapping(value = "/")
public String postUser(@ModelAttribute User user){
users.put(user.getId(), user);
return "success";
}

/**
* 处理GET 请求, 用来获取指定用户信息
* url中的id可通过@PathVariable绑定到函数的参数中
*/
@ApiOperation(value = "获取用户信息", notes = "根据id获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户编号(必填)", required = true)
@GetMapping(value = "/{id}")
public User getUser(@PathVariable Long id){
return users.get(id);
}

/**
* 处理PUT 请求, 用来更新指定用户信息
*/
@ApiOperation(value = "修改用户信息", notes = "根据id修改用户详细信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户编号(必填)", required = true),
@ApiImplicitParam(name = "name", value = "用户名称"),
@ApiImplicitParam(name = "age", value = "用户年龄"),
})
@PutMapping(value = "/{id}")
public String putUser(@PathVariable Long id, @ModelAttribute User user){
User u = users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(id, u);
return "success";
}

/**
* 处理DELETE 请求, 用来删除指定用户信息
*/
@ApiOperation(value = "删除用户", notes = "根据id删除指定用户详细信息")
@ApiImplicitParam(name = "id", value = "用户编号(必填)", required = true)
@DeleteMapping(value = "/{id}")
public String deleteUser(@PathVariable Long id){
users.remove(id);
return "success";
}

}

访问Swagger2

访问地址: http://localhost:8080/swagger-ui.html

Swagger注释API详细说明

作用范围 API 使用位置 作用
对象属性 @ApiModelProperty 用在出入参数对象的字段上 添加和操作模型属性的数据
协议集描述 @Api 用于controller类上 将类标记为一种Swagger资源
协议描述 @ApiOperation 用在controller的方法上 描述针对特定路径的操作或通常是 http 方法
Response集 @ApiResponses 用在controller的方法上 允许多个 ApiResponse 对象列表的包装
Response @ApiResponse 用在 @ApiResponses里边 描述操作的可能响应
非对象参数集 @ApiImplicitParams 用在controller的方法上 允许多个 ApiImplicitParam 对象列表的包装
非对象参数描述 @ApiImplicitParam 用在@ApiImplicitParams的方法里边 表示 api 操作中的单个参数
描述返回对象的意义 @ApiModel 用在返回对象类上 提供模型信息

@ApiImplicitParam

可用在@ApiImplicitParams 注解中,也可以单独使用,指定一个请求参数的各个方面

示例:

1
2
3
4
5
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户编号(必填)", required = true),
@ApiImplicitParam(name = "name", value = "用户姓名", dataType = "String"),
@ApiImplicitParam(name = "age", value = "用户年龄", dataType = "Long"),
})

@ApiOperation

添加这个注解到任何controller的rest方法上来给方法添加基本的描述

示例:

1
2
3
4
5
6
@ApiOperation(value = "用户列表", notes = "获取所有用户列表")
@GetMapping(value = "/")
public List<User> getUserList(){
List<User> list = new ArrayList<>(users.values());
return list;
}

@ApiModelProperty

这个注解用来在数据模型对象中的属性上添加一些描述,会在Swagger UI中展示模型的属性

示例:

1
2
3
4
5
@ApiModelProperty(value = "用户编号", name = "id", example = "1", required = true)
private Long id;

@ApiModelProperty(value = "用户姓名", name = "name", example = "Ray")
private String name;

@Api

可以添加这个注解在controller上,去添加一个基本的controller说明

示例:

1
2
3
4
5
6
@Api(value = "UserController", description = "用户实体类控制器")
@RestController
@RequestMapping(value = "/users")
public class UserController {
...
}
-------------- 本文结束  感谢您的阅读 --------------