SpringBoot工程实践:Swagger进阶-使用自定义的Swagger页面

原创 KimZing 2020-01-16 23:22

一、简介

Swagger的使用网上已经有很多的介绍了,这里就不重复的太多,但是Swagger官方的UI界面不是太直观,偶然发现一个开源项目knife4j, 在此感谢作者的奉献。这个项目没有使用Swagger官方的UI界面,重新定义了一套符合国人使用习惯的UI,感觉不错,就拿来用用。但是这个项目的文档有点乱,特别是刚出了2.0.1版本,没有找到详细的使用文档,所以根据项目的源码做了一些摸索,记录于此。

一、环境准备-SpringBoot

1
2
3
4
5
6
7
8
9
10
11
12
<!--可以只引入该包,这个包包含了所有依赖,暴露/doc.html页面-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.1</version>
</dependency>
<!--可选,引入后,原/swagger-ui.html提供的页面仍可正常使用-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

二、Swagger配置

1. 编写Swagger属性类

这样可以通过配置文件对Swagger进行配置,简单省事,不用改代码

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
@Data
@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties {

/**
* 标题
*/
private String title;

/**
* 文档描述
*/
private String description;

/**
* 项目路径
*/
private String termsOfServiceUrl;

/**
* 作者
*/
private String authorName;

/**
* 邮箱
*/
private String authorEmail;

/**
* 作者主页
*/
private String authorUrl;

/**
* 版本
*/
private String version;

/**
* 扫描的路径
*/
private String basePackage;

}

2. 编写Swagger配置类

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
// 声名为配置类
@Configuration
// 开启Swagger
@EnableSwagger2
// 导入Swagger属性类
@EnableConfigurationProperties(value = SwaggerProperties.class)
// 开启Knife4j的扩展功能, 如果没有需要,可以不开启
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {

@Bean
public Docket createRestApi(SwaggerProperties swaggerProperties) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(
new ApiInfoBuilder()
.title(swaggerProperties.getTitle())
.description(swaggerProperties.getDescription())
.termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
.contact(new Contact(swaggerProperties.getAuthorName(),
swaggerProperties.getAuthorUrl(),
swaggerProperties.getAuthorEmail()))
.version(swaggerProperties.getVersion())
.build())
.select()
.apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
.paths(PathSelectors.any())
.build();
}

}

3. 配置文件

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
# Swagger配置
swagger:
title: SpringBoot Web Swagger使用示例
description: swagger使用示例
termsOfServiceUrl: http://localhost:8080/api
authorName: kimzing
authorEmail: kimzing@163.com
authorUrl: http://kimzing.com
version: 1.0.0
basePackage: com.kimzing.web.controller

# knife开源的swagger ui配置
knife4j:
# 是否是生产环境,如果是生产环境会默认关闭swagger
production: false
# 配置自定义markdown文件的位置
markdowns: classpath:markdown/*
# 配置认证功能
basic:
# 是否开启认证
enable: true
# 用户名
username: admin
# 密码
password: 123456

三、Swagger原生注解

1. 注解说明

Swagger的使用注解有很多,这里我们只讲最常用的注解,以及这些注解中最常用的属性。

  • @Api(tags = {“用户操作”})
    • 加在controller类上
    • tags表示该类的标签,在页面会独立显示一个菜单
  • @ApiOperation(value = “保存用户”, notes = “保存时,ID由数据库生成,无需填写,有则忽略”, tags = “保存”)
    • 加在相应的请求处理方法上
    • value表示该方法的说明
    • notes相当于对该方法的详细说明,也就是更加完整的描述
    • tags 表示标签,,在页面会独立显示一个菜单
  • @ApiImplicitParam(name = “id”, value = “用户ID”, defaultValue = “1”)
    • 方法只有一个基本类型参数时加在方法上。方法有多个参数时加在@ApiImplicitParams内
    • name 参数中属性的名字
    • value 对这个属性的描述
    • defaultValue 默认值,这个还是有必要填写的,在页面进行请求时,会自动填充
  • @ApiImplicitParams(value = {})
    • 用在请求方法上
    • 这个注解必须和@ApiImplicitParam配合使用
    • 当请求方法中的请求参数很多的时候,例如saveUser(String username, Integer age, Date birthday, String phone)
  • @ApiParam(value = “当前页”, defaultValue = “1”)
    • 加在请求方法的普通参数上
    • value的值是对该参数的说明
    • 与@ApiImplicitParam使用的效果等同,根据个人喜好进行使用
  • @ApiModel(value = “用户信息”)
    • 加在请求方法的对象类
    • value 对该对象参数的描述
    • 例如有一个请求方法save(UserDTO userDTO), 则需要加在UserDTO这个类上面(可以参照下面的示例)
  • @ApiModelProperty(value = “用户ID”, example = “1”)
    • 加在请求方法的参数对象的属性上
    • value 对该属性的描述
    • example 属性的示例值,在页面会自动填充该值

2. 使用示例

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
@Api(tags = {"用户操作"})
@RestController
@RequestMapping(value = "/user")
public class UserController {

@PostMapping
@ApiOperation(value = "保存用户", notes = "保存时,ID由数据库生成,无需填写,有则忽略", tags = "保存")
public ApiResult save(@RequestBody UserDTO userDTO) {
return ApiResult.success();
}

@DeleteMapping("/{id}")
@ApiOperation(value = "删除用户", notes = "删除后无法恢复", tags = "删除")
@ApiImplicitParam(name = "id", value = "用户ID", defaultValue = "1")
public ApiResult remove(@PathVariable Long id) {
return ApiResult.success();
}

@PutMapping
@ApiOperation(value = "更新用户", notes = "id必填,其它属性存在则更新,否则忽略", tags = "更新")
public ApiResult update(@RequestBody UserDTO userDTO) {
return ApiResult.success();
}

@GetMapping("/{id}")
@ApiOperation(value = "查找用户", notes = "根据id查找单个用户", tags = "查找")
public ApiR