Spring Boot 实战 —— 集成 Swagger 生成 RESTful API 文档

简介

Swagger 官网是这么描述它的:The Best APIs are Built with Swagger Tools

Swagger 是一套基于 OpenAPI 规范构建的开源工具,可以帮助我们设计、构建、记录以及使用 Rest API。Swagger 主要包含了以下三个部分:

  1. Swagger Editor:基于浏览器的编辑器,我们可以使用它编写我们 OpenAPI 规范。
  2. Swagger UI:它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档,后文我将使用浏览器来查看并且操作我们的 Rest API。
  3. Swagger Codegen:它可以通过为 OpenAPI(以前称为 Swagger)规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

Spring Boot 使得开发 RESTful 服务变得简单。那么编写 Spring Boot 接口,为何要用 Swagger 呢?

  • 代码改变,文档就会改变。只需要少量的注释,Swagger 就可以根据代码自动生成 API 文档。
  • Swagger UI 是一份交互式的 API 文档,可以直接在 Web 界面调用 API。这里有一份 Swagger UI 的 Live Demo,看看官方是怎么写 RESTful API 的。

添加依赖

pom.xml 引入 Swagger 相关的依赖:

1
2
3
4
5
6
7
8
9
10
11
12
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<!-- swagger2 ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>

使用 property 定义了 Swagger 的版本,因此还需要添加:

1
<swagger.version>2.9.2</swagger.version>

依赖说明:

  • springfox-swagger2 Swagger 的 Java 实现
  • springfox-swagger-ui Swagger UI 页面的依赖

Swagger 配置类

使用注解 @Configuration 编写 Swagger 配置类—— SwaggerConfig

新建 config 的包,创建 SwaggerConifg 的配置类:

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
//通过@Configuration注解,让Spring来加载该类配置
@Configuration
//通过@EnableSwagger2注解来启用Swagger2
@EnableSwagger2
//@ConditionalOnExpression 为Spring的注解,用户是否实例化本类,用于是否启用Swagger的判断(生产环境需要屏蔽Swagger)
@ConditionalOnExpression("${swagger.enable:true}")
public class SwaggerConfig {

// select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,
// Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)
@Bean
public Docket createRestApi() {
// apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中
ApiInfo apiInfo = new ApiInfoBuilder()
.title("标题: Spring Boot 项目集成 Swagger 示例文档")
.description("描述: 我的博客地址是 https://michael728.github.io")
.termsOfServiceUrl("https://michael728.github.io/")
.version("1.0")
.build();

Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
// select()函数返回一个ApiSelectorBuilder实例
.select()
// 决定了暴露哪些接口给 Swagger
.paths(regex("/api/.*"))
.build()
.useDefaultResponseMessages(false)
.glo
return docket;
}
}

说明:

  • @Configuration 是告诉 Spring Boot 需要加载这个配置类;
  • @EnableSwagger2 是启用 Swagger2,没加的话,就看不到效果了;
  • ApiInfo 对象用来设置一些文档的版本号、联系人邮箱、网站、版权、开源协议等等信息(这些基本信息会展现在文档页面中)。并使用 Docket.apiInfo() 方法来设置;
  • Docket 上增加筛选。提供了 apis()paths() 两个方法帮助我们在不同级别上过滤接口:
    • apis() 这种方式我们可以指定包名的方式,让 Swagger 只去某些包下面扫描;
    • paths() 这种方式可以通过筛选 API 的 url 来进行筛选;
  • @ConditionalOnExpression("${swagger.enable:true}") 这个注解控制了是否启用 Swagger,我们需要在 appplication.properties 中加上 swagger.enable=true

编写控制器类——Controller 类

我们先介绍一下在用 Swagger 时的常用注解:

  • @API 类的注解,可以给控制器增加描述和标签信息。用在请求的类上,代表了这个类是 Swagger 的资源
    • tags:控制器标签,对该类进行「分类」,参数是个字符串数组,如果配置了多个值,会在多个分类中看到;
    • value:该参数没什么意义,在 UI 界面上并不显示,可不用配置
  • @ApiModel 类注解,对 API 涉及的对象做描述,可用于响应实体类,说明实体作用
    • value Model 展示时的名称,默认是 实体类的名称,比如 UserEntity
    • description 实体类的描述

model.jpg

类成员变量的的注解:

  • @ApiModelProperty 用在实体类的属性上
    • value 属性字段描述;
    • required 参数是否必选;
    • name 重写字段名称;
    • dataType 重写字段类型;
    • allowEmptyValue 是否允许为空;
    • allowbleValues 该字段允许的值。当我们 API 某个参数为枚举类型时,使用这个参数就可以清楚高速 API 使用者能允许传入的值

方法的注解:

  • @ApiOperation 描述方法的用途,用来展开对接口的描述
    • value 接口简要描述;
    • notes 接口发布说明,详细描述;
  • @ApiImplicitParams 用于描述接口的非对象参数集,一般与 @ApiImplicitParams 组合使用
  • @ApiImplicitParam 描述参数信息
    • value 参数意义的描述
    • name 参数名字;
    • required 默认 false,参数是否必传
    • dataType 参数数据类型,只作为标志说明,并没有实际验证
      • Long
      • String
    • paramType 参数类型,表示参数放在哪里
      • query,默认值,Query String 的方式传参,请求参数的获取:@RequestParam
      • path 路径参数,请求参数的获取:@PathVariable
      • header 请求参数的获取:@RequestHeader
  • @PathVariable 路径参数,给类似 @GetMappIng("/user/{id}") 参数通过路径传入

其他:

  • @ApiIgnore:用于类或者方法上,屏蔽接口不被显示在页面上;
  • @Profile({"dev","test"}):用于配置类上,表示对什么环境启用;
  • @ApiParam 不能直接用在方法上,而是用在方法的形参定义中,下文会有示例;

实体类示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
@Data
@ApiModel(value = "用户实体")
public class UserEntity {
public static final long serialVersionUID = 1L;
@ApiModelProperty(value = "用户 id")
private int id;
@ApiModelProperty(value = "用户名", required = true)
private String userName;
@ApiModelProperty(value = "密码" )
private String passWord;
@ApiModelProperty(value = "性别")
private UserSexEnum userSex;
@ApiModelProperty(value = "昵称" )
private String nickName;

public UserEntity(Integer id, String userName, String passWord) {
this.id = id;
this.userName = userName;
this.passWord = passWord;
}
}

下面是一个控制类的示例:

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
@RestController
@RequestMapping("/api/v1/")
@Api(tags = {"用户相关接口"}, value = "用户模块")
public class UserController {

// 模拟数据库
public static List<UserEntity> users = new ArrayList<>();

static {
UserEntity user1 = new UserEntity(1, "michael", "123");
UserEntity user2 = new UserEntity(2, "qq", "123");
UserEntity user3 = new UserEntity(3, "hh", "123");
users.add(user1);
users.add(user2);
users.add(user3);
}

@ApiOperation(value = "获取用户列表", notes = "获取全部用户信息")
@RequestMapping(value = "/users", method = RequestMethod.GET)
public List<UserEntity> getUsers() {
return users;
}

@ApiOperation(value = "查询单用户", notes = "根据用户id 查询其信息")
@ApiImplicitParam(name = "id", value = "用户id", paramType = "query", required = true)
@GetMapping("/user/{id}")
public UserEntity getUser(@PathParam("id") int id) {
UserEntity user = users.get(id);
return user;
}

@ApiOperation(value = "存储用户信息", notes = "存储用户详细信息")
@RequestMapping(value = "/user", method = RequestMethod.POST)
public UserEntity saveUser(@ApiParam(value = "用户信息", required = true)
@RequestBody UserEntity user) {
users.add(user);
return user;
}

@ApiOperation(value = "删除用户", notes = "根据用户id删除用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户id", required = true, paramType = "path")
})
@RequestMapping(value = "/user/{id}", method = RequestMethod.DELETE)
public int deleteUser(@PathVariable("id") int id) {
users.remove(id);
return id;
}


@ApiOperation(value = "更新用户信息", notes = "更新用户的个人信息")
@PutMapping("/user/")
public UserEntity updateUser(@RequestBody UserEntity user) {
int id = user.getId();
UserEntity oldUser = users.get(id);
users.set(id, user);
return user;
}
}

启动

启动应用,访问 localhost:8080/swagger-ui.html 可以访问到 Swagger UI,可以点击 Try it out 按钮,调用 API:

Jietu20190713-211403-swagger.jpg

页面上还会有一个 Models 的分类。Swagger UI 会根据我们在实体上使用的 @ApiModel@ApiModelProperty 注解来自动补充实体以及其属性的描述和备注。

model.jpg

示例代码

One More Thing

Web API 的风格

开发 API,先了解一下有哪些 Web API 的风格吧:

  • RPC:RPC 面向过程,RPC 形式的 API 组织形态是类和方法,API 的命名往往是一个动词,比如 GetUserInfo,CreateUser;
  • REST:REST 面向资源,也是下文将要介绍的一种 API 风格;
  • GraphQL:就是面向数据查询,采用GraphQL,甚至不需要有任何的接口文档,在定义了Schema之后,服务端实现Schema,客户端可以查看Schema,然后构建出自己需要的查询请求来获得自己需要的数据

REST

上文提到了 RESTful API 的概念,我觉得,不如趁机了解一下。因为在实际的项目中发现,并不是每个 Spring Boot 的开发人员都能意识到开发的 API 要尽量符合 RESTful 规则的。REST 实际上只是一种设计风格,它并不是标准。

术语:

  • Endpoint 终点,可以理解为路径,表示 API 的具体网址。
  • API(Application Programming Interface),应用程序编程接口
  • RESTRepresentational State Transfer 的缩写。如果一个架构符合 REST 原则,就称它为 RESTful 架构。RESTful API 就是 REST 风格的 API
    • Resource:资源,即数据。
    • Representational:某种表现形式,比如用 JSON,XML,JPEG 等;
    • State Transfer:状态变化。通过 HTTP 动词实现

在 RESTful 架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。

资源的操作

RESTful 的核心思想就是,客户端发出的数据操作指令都是”动词 + 宾语”的结构。比如,GET /articles 这个命令,GET 是动词,/articles 是宾语。

对于资源的具体操作类型,由 HTTP 动词表示(括号里是对应的 SQL 命令):

  • GET(SELECT):从服务器取出资源(一项或多项)。
  • POST(CREATE):在服务器新建一个资源。
  • PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
  • PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
  • DELETE(DELETE):从服务器删除资源

还有两个不常用的 HTTP 动词:

  • HEAD:获取资源的元数据。
  • OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的

知乎上的一个回答,我觉得很精辟:

  • 看 Url 就知道要什么
  • 看 http method 就知道干什么
  • 看 http status code 就知道结果如何

一位答主给出的示例:

1
2
3
4
GET /rest/api/getDogs --> GET /rest/api/dogs 获取所有小狗狗
GET /rest/api/addDogs --> POST /rest/api/dogs 添加一个小狗狗
GET /rest/api/editDogs/:dog_id --> PUT /rest/api/dogs/:dog_id 修改一个小狗狗
GET /rest/api/deleteDogs/:dog_id --> DELETE /rest/api/dogs/:dog_id 删除一个小狗狗

信息过滤 Filtering

如果记录数量很多,服务器不可能都将它们返回给用户。API 应该提供参数,过滤返回结果

  • ?limit=10:指定返回记录的数量
  • ?offset=10:指定返回记录的开始位置。
  • ?page=2&per_page=100:指定第几页,以及每页的记录数

参考

API 介绍

Michael翔 wechat
欢迎订阅 ヾノ≧∀≦)o
我知道是不会有人点的,但万一有人想不开呢👇