Spring Boot 整合 Swagger2 生成在线 API 文档

Posted by 彭楷淳 on 2021-01-22
Estimated Reading Time 6 Minutes
Words 1.6k In Total
Viewed Times

前后端分离后,维护接口文档基本上是必不可少的工作。一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了。当然这是一种非常理想的状态,实际开发中却很少遇到这样的情况,接口总是在不断的变化之中,有变化就要去维护,做过的小伙伴都知道这件事有多么头大!还好,有一些工具可以减轻我们的工作量,Swagger2 就是其中之一,至于其他类似功能但是却收费的软件,这里就不做过多介绍了。本文主要和大伙来聊下 在Spring Boot 中如何整合 Swagger2。

创建项目


引入依赖

pom.xml 中加入两个 Swagger2 相关的依赖,完整的依赖如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger -->

相关配置

Swagger2 的配置也是比较容易的,在项目创建成功之后,只需要开发者自己提供一个 Docket 的 Bean 即可,如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("com.antonio.hello.swagger.controller"))
.paths(PathSelectors.any())
.build().apiInfo(new ApiInfoBuilder()
.title("SpringBoot整合Swagger")
.description("SpringBoot整合Swagger,详细信息......")
.version("9.0")
.contact(new Contact("Antonio","www.antoniopeng.com","antoniopeng@foxmail.com"))
.license("The Apache License")
.licenseUrl("http://www.antoniopeng.com")
.build());
}
}

这里提供一个配置类,首先通过 @EnableSwagger2 注解启用 Swagger2 ,然后配置一个 Docket Bean,这个 Bean 中,配置映射路径和要扫描的接口的位置,在 apiInfo 中,主要配置一下 Swagger2 文档网站的信息,例如网站的 title,网站的描述,联系人的信息,使用的协议等等。如此,Swagger2 就算配置成功了,非常方便。

此时启动项目,访问 http://localhost:8080/swagger-ui.html 能够看到 swagger 页面,说明已经配置成功了:

创建接口


接下来就是创建接口了,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
@RestController
@Api(tags = "用户管理相关接口")
@RequestMapping("/user")
public class UserController {

@PostMapping("/")
@ApiOperation("添加用户的接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四"),
@ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "深圳", required = true)
})
public RespBean addUser(String username, @RequestParam(required = true) String address) {
return new RespBean();
}

@GetMapping("/")
@ApiOperation("根据id查询用户的接口")
@ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99", required = true)
public User getUserById(@PathVariable Integer id) {
User user = new User();
user.setId(id);
return user;
}

@PutMapping("/{id}")
@ApiOperation("根据id更新用户的接口")
public User updateUserById(@RequestBody User user) {
return user;
}
}

这里边涉及到多个 API,我来向小伙伴们分别说明:

  1. @Api 注解可以用来标记当前 Controller 的功能。
  2. @ApiOperation 注解用来标记一个方法的作用。
  3. @ApiImplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入。
  4. 如果有多个参数,则需要使用多个 @ApiImplicitParam 注解来描述,多个 @ApiImplicitParam 注解需要放在一个 @ApiImplicitParams 注解中。
  5. 需要注意的是,@ApiImplicitParam 注解中虽然可以指定参数是必填的,但是却不能代替 @RequestParam(required = true) ,前者的必填只是在 Swagger2 框架内必填,抛弃了 Swagger2 ,这个限制就没用了,所以假如开发者需要指定一个参数必填,@RequestParam(required = true) 注解还是不能省略。
  6. 如果参数是一个对象(例如上文的更新接口),对于参数的描述也可以放在实体类中。例如下面一段代码:
1
2
3
4
5
6
7
8
9
10
11
12
@ApiModel
public class User {

@ApiModelProperty(value = "用户id")
private Integer id;
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "用户地址")
private String address;

// 省略 getter/setter
}

好了,经过如上配置之后,接下来,刷新刚刚打开的页面,可以看到如下效果:

img

可以看到,所有的接口这里都列出来了,包括接口请求方式,接口地址以及接口的名字等,点开一个接口,可以看到如下信息:

img

可以看到,接口的参数,参数要求,参数默认值等等统统都展示出来了,参数类型下的 query 表示参数以 key/value 的形式传递,点击右上角的 Try it out,就可以进行接口测试:

img

点击 Execute 按钮,表示发送请求进行测试。测试结果会展示在下面的 Response 中。

注意:参数类型下面的 query 表示参数以 key/value 的形式传递,这里的值也可能是 body,body 表示参数以请求体的方式传递,例如上文的更新接口,如下:

img

当然还有一种可能就是这里的参数为 path,表示参数放在路径中传递,例如根据 id 查询用户的接口:

img

当然,除了这些之外,还有一些响应值的注解,都比较简单,小伙伴可以自己摸索下。

给 Swagger 换个新皮肤


knife4j 简介

knife4j 是 springfox-swagger 的增强UI实现,为Java开发者在使用 Swagger 的时候,提供了简洁、强大的接口文档体验。knife4j完全遵循了springfox-swagger中的使用方式,并在此基础上做了增强功能,如果你用过Swagger,你就可以无缝切换到knife4j。

1
2
3
4
5
6
<!--整合Knife4j-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.4</version>
</dependency>Copy to clipboardErrorCopied

在 Swagger2Config 中增加一个 @EnableKnife4j 注解,该注解可以开启knife4j的增强功能;

1
2
3
4
5
6
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {

}

附:Spring Security 中的配置


如果我们的 Spring Boot 项目中集成了 Spring Security,那么如果不做额外配置,Swagger2 文档可能会被拦截,此时只需要在 Spring Security 的配置类中重写 configure 方法,添加如下过滤即可:

1
2
3
4
5
6
7
@Override
public void configure(WebSecurity web) throws Exception {
web.ignoring()
.antMatchers("/swagger-ui.html")
.antMatchers("/v2/**")
.antMatchers("/swagger-resources/**");
}

更多干货请移步:https://antoniopeng.com


If you like this blog or find it useful for you, you are welcome to comment on it. You are also welcome to share this blog, so that more people can participate in it. If the images used in the blog infringe your copyright, please contact the author to delete them. Thank you !