Swagger和knife4j的使用_如何使用swagger+knife4j

---

knife4j是加强的swagger文档，功能更加完善，所以需要了解knife4j的朋友可以直接跳转到第二部分。

一、Swagger概述及使用

1.概述

Swagger 是一个规范和完整的框架，用于接口文档的在线自动生成，我们常使用Swagger-ui，一个无依赖的HTML、js和CSS的集合，可以为Swagger兼容API动态生成优雅的文档。

2.使用说明

2.1 添加swagger的依赖

	<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
1
2
3
4
5

2.2.创建Swagger配置类（随用随复制）

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


/**
 * Swagger2配置类
 * 在与spring boot集成时，放在与Application.java同级的目录下。
 * 通过@Configuration注解，让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */

@Configuration
@EnableSwagger2
public class Swagger {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("使用Swagger2构建RESTful APIs)")
                .description("海苔大王")
                .termsOfServiceUrl("https://blog.csdn.net/m0_54070163")
                .contact(new Contact("海苔大王","https://blog.csdn.net/m0_54070163","feihaitai@email.com"))
                .version("1.0")
                .build();
    }
}
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

2.3 在项目中的注释

使用到的注解及其说明：

@Api：用在类上面，说明当前类的作用
@ApiOperation：注解来给API增加方法说明
@ApiImplicitParams：用来注解来给方法入参增加说明
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请添加参数"
response：抛出异常的类
@ApiModel：@ApiModelProperty：描述一个model的属性

2.4 使用时遇到的错误

swagger Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException

原因：spring boot2.6.X 继承swagger报错，因为Springfox使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher。

解决办法：在application.properties或者application.yaml中添加

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

2.5 例子

2.5.1 实体类中的使用

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User的对象",description = "用户信息表")
public class User implements Serializable {
    @ApiModelProperty(value = "用户编号")
    private Integer uid;
    @ApiModelProperty(value = "用户名")
    private String uname;
    @ApiModelProperty(value = "用户密码")
    private String upassword;
    @ApiModelProperty(value = "用户住址")
    private String uaddress;
    @ApiModelProperty(value = "用户身份证号")
    private String uIdCard;
    @ApiModelProperty(value = "用户手机号")
    private String phoneNumber;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

2.5.2 控制类中的使用

@RestController
@Api(tags = {"用户接口模块"})
@Slf4j
public class UserController {
    /**
     * 添加用户
     *
     * 在使用对象封装参数进行传参时，需要在该对象添加注解，将其注册到swagger中
     *
     * 注意： 在后台采用对象接收参数时，Swagger自带的工具采用的是JSON传参，
     *     测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。
     *
     * @param user 用户类对象
     * @return
     * @throws Exception
     */
    @ResponseBody
    @RequestMapping(value="/doctor",  method= RequestMethod.POST )
    @ApiOperation(value="添加用户信息", notes="添加用户接收对象")
    public String addDoctor(@RequestBody User user) throws Exception{
        if(null == user || user.getUid() == null){
            log.info("添加用户失败");
        }
        try {
            System.out.println("成功----------->"+user.getUname());
        } catch (Exception e) {
            log.info("添加用户失败");
        }

        return user.toString();
    }

    /**
     * 删除用户
     * @param uid 用户ID
     * @return
     */
    @ResponseBody
    @RequestMapping(value="/doctor/{doctorId}",  method= RequestMethod.DELETE )
    @ApiOperation(value="删除用户信息", notes="返回字符串删除失败或删除成功")
    @ApiImplicitParam(paramType="query", name = "uid", value = "用户ID", example = "11",required = true, dataType = "int",dataTypeClass = Integer.class)
    public String deleteDoctor(@RequestParam Integer uid){
        if(uid > 2){
            return "删除失败";
        }
        return "删除成功";
    }
}
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

2.6 效果演示

访问 ：http://ip地址:端口号/swagger-ui/index.html

首页演示：

接口控制模块：

接口模块详情：

实体类：

二、knife4j概述及使用（目前最实用！！！）

1.概述

knife4j是swagger的增强版本，更加的小巧、轻量，功能也是更加的完善，UI也更加的清晰；可以从swagger到knife4j无缝切换。

2.knife4j的使用

2.1 添加knife4j的依赖

		<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>
1
2
3
4
5

引入knife4j之后，会自动引入swagger的相关依赖，要注意避免发生依赖冲突

2.2 创建配置类（与swagger的一致即可）

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


/**
 * Swagger2配置类
 * 在与spring boot集成时，放在与Application.java同级的目录下。
 * 通过@Configuration注解，让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */

@Configuration
@EnableSwagger2
public class Swagger {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("使用Swagger2构建RESTful APIs)")
                .description("海苔大王")
                .termsOfServiceUrl("https://blog.csdn.net/m0_54070163")
                .contact(new Contact("海苔大王","https://blog.csdn.net/m0_54070163","feihaitai@email.com"))
                .version("1.0")
                .build();
    }
}
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

2.3 创建yaml配置文件

# 增强功能
knife4j:
  enable: true
1
2
3

2.4 创建实体类和控制类（使用Swagger中用到的）

创建实体类

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User的对象",description = "用户信息表")
public class User implements Serializable {
    @ApiModelProperty(value = "用户编号")
    private Integer uid;
    @ApiModelProperty(value = "用户名")
    private String uname;
    @ApiModelProperty(value = "用户密码")
    private String upassword;
    @ApiModelProperty(value = "用户住址")
    private String uaddress;
    @ApiModelProperty(value = "用户身份证号")
    private String uIdCard;
    @ApiModelProperty(value = "用户手机号")
    private String phoneNumber;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

创建控制层：

@RestController
@Api(tags = {"用户接口模块"})
@Slf4j
public class UserController {
    /**
     * 添加用户
     *
     * 在使用对象封装参数进行传参时，需要在该对象添加注解，将其注册到swagger中
     *
     * 注意： 在后台采用对象接收参数时，Swagger自带的工具采用的是JSON传参，
     *     测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。
     *
     * @param user 用户类对象
     * @return
     * @throws Exception
     */
    @ResponseBody
    @RequestMapping(value="/doctor",  method= RequestMethod.POST )
    @ApiOperation(value="添加用户信息", notes="添加用户接收对象")
    public String addDoctor(@RequestBody User user) throws Exception{
        if(null == user || user.getUid() == null){
            log.info("添加用户失败");
        }
        try {
            System.out.println("成功----------->"+user.getUname());
        } catch (Exception e) {
            log.info("添加用户失败");
        }

        return user.toString();
    }

    /**
     * 删除用户
     * @param uid 用户ID
     * @return
     */
    @ResponseBody
    @RequestMapping(value="/doctor/{doctorId}",  method= RequestMethod.DELETE )
    @ApiOperation(value="删除用户信息", notes="返回字符串删除失败或删除成功")
    @ApiImplicitParam(paramType="query", name = "uid", value = "用户ID", example = "11",required = true, dataType = "int",dataTypeClass = Integer.class)
    public String deleteDoctor(@RequestParam Integer uid){
        if(uid > 2){
            return "删除失败";
        }
        return "删除成功";
    }
}
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

2.5 效果演示

访问 ：http://localhost:8080/doc.html