swagger-02-配置swagger

1.4 配置swagger

package com.example.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
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;

import java.util.ArrayList;

/**
 * @author CNCLUKZK
 * @create 2022/8/7-0:47
 */
@Configuration // 标明是配置类
//@EnableSwagger2  //开启swagger2功能 供3.0以下使用,swagger老版本
@EnableOpenApi
//@Profile({"dev","test"})
public class SwaggerConfig {
    //配置了Swagger 的Docket bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)// DocumentationType.OAS_30 固定的，代表swagger3.0
                .groupName("分组1") // 如果配置多个文档的时候，那么需要配置groupName来分组标识
                .apiInfo(apiInfo());
        //RequestHandlerSelectors
    }

    //配置Swagger信息=apiInfo
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("application API")
                .version("v1.0")
                .description("application API manage")
                .contact(new Contact("zk","http://localhost:8080/zk","123456@163.com"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .termsOfServiceUrl("http://localhost:8080/zk")  用于定义服务的域名
                .extensions(new ArrayList<>())
                .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

1.5 swagger配置扫描接口

public ApiSelectorBuilder select() {
  return new ApiSelectorBuilder(this);
}
1
2
3

• 扫描接口Docket.select()

/**
     * 配置了Swagger 的Docket bean实例
     * RequestHandlerSelectors配置扫描接口的方式
     * basePackage指定扫描的包
     * withMethodAnnotation扫描某注解的方法
     * withClassAnnotation扫描某注解的类
     * .enable(false)是否启动swagger,false不启动，无法在浏览器访问
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)// DocumentationType.OAS_30 固定的，代表swagger3.0
                .groupName("分组1") // 如果配置多个文档的时候，那么需要配置groupName来分组标识
                .apiInfo(apiInfo())
                .select() // select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))// 用于指定扫描哪个包下的接口
                //paths 指定扫描路径  PathSelectors.ant("/app/**")在controller包下，请求路径是/app/**可以扫描到
                .paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档，可以配置这里
                .build();   //建造者模式
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

1.5.1 Swagger只在生产环境中使用

• 在正式发布的时候，关闭Swagger! 出于安全考虑。还节省运行的内存，

• • 判断是不是生产环境flag=false
  • 注入enable(flag)

package com.example.config;

import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
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;

import java.util.ArrayList;

/**
 * @author CNCLUKZK
 * @create 2022/8/7-0:47
 */
@Configuration // 标明是配置类
//@EnableSwagger2  //开启swagger2功能 供3.0以下使用,swagger老版本
@EnableOpenApi
//@Profile({"dev","test"})/**/
public class SwaggerConfig {

    /**
     * 配置了Swagger 的Docket bean实例
     * RequestHandlerSelectors配置扫描接口的方式
     * basePackage指定扫描的包
     * withMethodAnnotation扫描某注解的方法
     * withClassAnnotation扫描某注解的类
     * .enable(false)是否启动swagger,false不启动，无法在浏览器访问
     */
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        //通过environment.acceptsProfiles配置文件中设置的环境来判断是否在设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.OAS_30)// DocumentationType.OAS_30 固定的，代表swagger3.0
                .groupName("分组1") // 如果配置多个文档的时候，那么需要配置groupName来分组标识
                .apiInfo(apiInfo())
                .enable(flag)
                .select() // select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))// 用于指定扫描哪个包下的接口
                //paths 指定扫描路径  PathSelectors.ant("/app/**")在controller包下，请求路径是/app/**可以扫描到
                .paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档，可以配置这里
                .build();   //建造者模式
    }

    //配置Swagger信息=apiInfo
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("application API")
                .version("v1.0")
                .description("application API manage")
                .contact(new Contact("zk","http://localhost:8080/zk","123456@163.com"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .termsOfServiceUrl("http://localhost:8080/zk")  用于定义服务的域名
                .extensions(new ArrayList<>())
                .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
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

• 禁用方法2：使用注解@Profile({“dev”,“test”}) 表示在开发或测试环境开启，而在生产关闭。（推荐使用）

• 禁用方法3：使用注解@ConditionalOnProperty(name = “swagger.enable”, havingValue = “true”) 然后在测试配置或者开发配置中 添加 swagger.enable = true 即可开启，生产环境不填则默认关闭Swagger.

swagger.enable: true
1

1.6 配置API文档的分组

• 单个分组

new Docket(DocumentationType.OAS_30)// DocumentationType.OAS_30 固定的，代表swagger3.0
                .groupName("分组1");
1
2

• 配置多个分组，需要配置多个docket实例bean,bean方法名不能重名，spring bean重名会出问题。

@Bean
public Docket docket1(Environment environment){
    return new Docket(DocumentationType.OAS_30)// DocumentationType.OAS_30 固定的，代表swagger3.0
            .groupName("分组2");
}
@Bean
public Docket docket2(Environment environment){
    return new Docket(DocumentationType.OAS_30)// DocumentationType.OAS_30 固定的，代表swagger3.0
            .groupName("分组3");
}
1
2
3
4
5
6
7
8
9
10

1.协同开发时，各自的SwaggerConfig配置类配置各自的docket，扫描的的自己的包

2.环境需要配置合适

下一篇：swagger-03-文档注释使用