Swagger Knife4j 使用总结

使用 Swagger 和 Knife4j 来增强 API 文档和界面，方便开发者做一些简单的功能测试，也方便了前后端联调

Step 1. 导入依赖

1
2
3
4
5
6
7
8
9
10
11
12
<!-- https://doc.xiaominfo.com/docs/quick-start#openapi2  Swagger + Knife4j -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>
<!-- Hibernate Validator for data validation -->
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.2.5.Final</version>
</dependency>

Step 2. 创建 SwaggerConfig 配置类

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
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
package com.xuan.springbootinit.config;

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
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.EnableSwagger2WebMvc;

/**
* @Description: Swagger文档配置
* @Author: Xuan Cai
* @Date: 2024/7/22
*/
@Configuration
@EnableSwagger2WebMvc
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {
    /**
     * openApiExtensionResolver
     */
    private final OpenApiExtensionResolver openApiExtensionResolver;

    /**
    * @Description: 构造函数
    * @Param:
    * @return: [com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver]
    * @Author: Xuan Cai
    * @Date: 2024/7/22
    */
    @Autowired
    public SwaggerConfig(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    /**
     * 所有api
     *
     * @return
     */
    @Bean(value = "allApi")
    public Docket allApi() {
        // 命名，该api分组的名字，以及对应的controller包的全路径
        return getDocket("1.所有api", "com.xuan.springbootinit.controller");
    }

    /**
     * 其他api
     *
     * @return
     */
    @Bean(value = "otherApi")
    public Docket otherApi() {
        // 命名，该api分组的名字，以及对应的controller包的全路径
        return getDocket("2.其他api(根据业务取名)", "com.xuan.springbootinit.controller");
    }



    /**
    * @Description: 根据分组名称和package名称获取Docket
    * @Param: springfox.documentation.spring.web.plugins.Docket
    * @return: [java.lang.String, java.lang.String]
    * @Author: Xuan Cai
    * @Date: 2024/7/22
    */
    private Docket getDocket(String groupName, String packagePath) {
        //系统启动之后访问地址：http://127.0.0.1:port/api/doc.html#
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分组名称
                .groupName(groupName)
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage(packagePath))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions("1.0.0版本"));
        return docket;
    }

    /**
    * @Description: 主页信息配置
    * @Param: springfox.documentation.service.ApiInfo
    * @return: []
    * @Author: Xuan Cai
    * @Date: 2024/7/22
    */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("默认项目接口文档")
                .description("默认项目接口文档")
                .contact(new Contact("Xuan Cai", "", "??@??.??"))
                .version("1.0")
                .build();
    }
}

Step 3. 创建 Param 类，注解 controller 层的接口

创建 Param 类

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
package com.xuan.springbootinit.pojo.Param;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import javax.validation.constraints.NotNull;
import java.util.Date;

/**
 * Created with IntelliJ IDEA.
 *
 * @Author: Xuan Cai
 * @Date: 2024/07/23/22:49
 * @Description:
 */
@Data
public class UserParam {
	
    // @NotNull(message = "名字不能为空") 表示该参数为非空，然后配合接口上的注解@Valid一起使用
    // @ApiModelProperty(value = "你的名字", example = "caixuan") API文档界面的说明和默认值
    @NotNull(message = "名字不能为空")
    @ApiModelProperty(value = "你的名字", example = "caixuan")
    private String userName;

}

注解 controller 层的接口

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 这种注解较为常用，用于处理json形式的参数
@ApiOperation(value = "打个招呼")
@PostMapping("/hello")
public BaseResponse<String> hello(@Valid @RequestBody UserParam userParam) {
    String hello = null;
    try{
        hello = helloService.sayHello(userParam);
    } catch (Exception e) {
        return ResultUtils.error(50000, e.getMessage());
    }
    return ResultUtils.success(hello);
}


文档界面：

image-20240724000434839

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// 这种注解能够使文档非常清晰
// 处理文件时更多使用这种注解
@ApiOperation(value = "告别")
@PostMapping("/bye")
@ApiImplicitParams({
    @ApiImplicitParam(name = "userName", value = "你的名字", example = "caixuan", required = true)
})
public BaseResponse<String> bye(@ModelAttribute UserParam userParam) {
    String bye = null;
    try{
        bye = helloService.sayBye(userParam);
    } catch (Exception e) {
        return ResultUtils.error(50000, e.getMessage());
    }
    return ResultUtils.success(bye);
}

文档界面：

image-20240724000442610