Swagger3+knife4j的使用

一、导包

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

        <!--knife4j-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>
1
2
3
4
5
6
7
8
9
10
11
12
13

二、写配置类

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket initDocket(Environment env) {

        //设置要暴漏接口文档的配置环境
        //设置要显示的Swagger环境
        Profiles profile = Profiles.of("test","dev");
        //获取项目的环境：
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = env.acceptsProfiles(profile);
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .enable(flag)//是否启动swagger 默认为true ,如果为false，则Swagger不能再浏览器中访问
                .select()
                //RequestHandlerSelectors,配置要扫描接口的方式
                .apis(RequestHandlerSelectors.basePackage("com.zdsoft.datafactory.controller")) //指定要扫描的包
//                .apis(RequestHandlerSelectors.any())   //扫描全部
                //.apis(RequestHandlerSelectors.none()):不扫描
                //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)):扫描类上的注解，参数是一个注解的反射对象
                //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)):扫描方法上的注解
//                .apis(RequestHandlerSelectors.basePackage("com.zhao.controller"))
                //paths()过滤什么路径(url)
                //paths(PathSelectors.ant("/zhao/**")) 就是在localhost:8080/zhao  后面的路径
//                .paths(PathSelectors.ant("/zhao/**"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                //右上角 组（有几个Docket，有几个组）
                .groupName("第一组");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("第一组的Swagger3-接口文档")
                .description("第一组")
                .contact(new Contact("第一组", "https://blog.csdn.net/qq_57581439?type=blog", "XXXX@qq.com "))
                .version("V1.0")
//                .license("Apache 2.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

三、测试

浏览器访问http://localhost:8080/swagger-ui/即可访问到swagger3初始页面

浏览器访问http://localhost:8080/doc.html即可访问knife4j初始页面

四、swagger2注解

4.1 类

@Api()：表示这个类是 swagger 资源

tags：表示说明内容，只写 tags 就可以省略属性名
value：同样是说明，不过会被 tags 替代，没卵用

4.2 方法上

@ApiOperation() ：对方法的说明，注解位于方法上

value：方法的说明
notes：额外注释说明
response：返回的对象
tags：这个方法会被单独摘出来，重新分组，若没有，所有的方法会在一个Controller分组下

4.3 方法入参

@ApiParam()：对方法参数的具体说明，用在方法入参括号里，该注解在post请求参数时，参数名不显示

name：参数名
value：参数说明
required：是否必填

@ApiImplicitParam对方法参数的具体说明，用在方法上@ApiImplicitParams之内，该注解在get,post请求参数时，参数名均正常显示

name 参数名称
value 参数的简短描述
required 是否为必传参数
dataType 参数类型，可以为类名，也可以为基本类型（String，int、boolean等）指定也不起作用，没卵用
paramType 参数的传入（请求）类型，可选的值有path, query, body, header or form。

4.4 实体

@ApiModel描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

value : model的别名，默认为类名
description: model的详细描述

@ApiModelProperty描述一个model的属性

value 属性简短描述
example 属性的示例值
required 是否为必须值

4.5 header参数

@ApiImplicitParams({      
@ApiImplicitParam(
paramType="header",
name="USERTOKEN",
dataType="String",
required=true,
value="用户token")
    })

1
2
3
4
5
6
7
8
9

4.6 file入参

需要使用@RequestPart 注解

@ApiOperation(value = "上传文件接口",notes = "上传文件接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "上传人")
    })
    @PostMapping(value = "/uploadFile")
    public String uploadFile(
    @RequestParam("name") String name,
    @RequestPart("file") MultipartFile file){
        
    }

1
2
3
4
5
6
7
8
9
10
11

五、swagger3注解与2相差很多，但也兼容了2的注解，区别如下

标注在实体类上（与lombok连用）

注意这里的属性名只能试小写，有大写的显示不出来，除非把private改为public

@Data
@ApiModel(value = "用户类",description = "用户")
public class User {
    @Schema(description = "用户名")
    private String username;
    @Schema(description = "密码")
    private String password;
}
1
2
3
4
5
6
7
8

解决办法（手动加get、set方法）

@Data
@ApiModel(value = "用户类",description = "用户")
public class User {
    @Schema(description = "用户名")
    private String userName;
    @Schema(description = "密码")
    private String passWord;

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public String getPassWord() {
        return passWord;
    }

    public void setPassWord(String passWord) {
        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

标注在控制器上：

@RestController
@Api(tags = "用户信息处理")
public class HelloController {
    @GetMapping("/user")
    @ApiOperation("这里写这个是干嘛的，方便swagger中看，就是和上面@Role中内容写一样就行")
    //这里写入参(如果传的是实体类就不需要写@ApiImplicitParams里面的值)
//    @ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用户名",required = true),
//            @ApiImplicitParam(name = "password", value = "密码")})
    public R<StopWatch> ok(@RequestBody StopWatch stopWatch){
        System.out.println(stopWatch);
        StopWatch stopWatch1 = new StopWatch();
        stopWatch1.setsId(1L);
        return R.Success(stopWatch1);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

六、拦截器放行

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    TokenInterceptor tokenInterceptor;

    /**
     * 拦截器
     * @param registry
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 注册token拦截器
        registry.addInterceptor(tokenInterceptor)
                .addPathPatterns("/**")
                .excludePathPatterns("/doc.html")
                .excludePathPatterns("/**/swagger-ui/**")
                .excludePathPatterns("/**/swagger-resources/**")
                .excludePathPatterns("/**/v3/**")
        ;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

参考文章：Swagger 使用总结_sunny_1100的博客-CSDN博客
参考文章：Spring boot集成Swagger3_跳着迪斯科学Java的博客-CSDN博客_swagger3依赖