【swagger】springboot项目中配置Swagger的两种方式以及swagger权限验证、安全控制

前言

swagger是什么？
    Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

    Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

一、springboot配置Swagger的两种方式

方式1：使用配置文件来配置Swagger设置

1.在pom.xml文件添加依赖

        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.8.0.RELEASE</version>
        </dependency>

1
2
3
4
5
6

2.在配置文件application.yml添加配置

swagger:
  base-package: 'com.itfuture.controller'
  base-path: '/**'
  title: '注解方式的Swagger'
  description: '这是注解方式的Swagger'
  version: '2.0'
  license-url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
  license: 'The Apache License'
  contact:
    name: 'itfuture'
    url: 'https:www.baidu.com'
    email: '******@qq.com'

1
2
3
4
5
6
7
8
9
10
11
12
13

3.在启动类添加注解@EnableSwagger2Doc

@EnableSwagger2Doc
@SpringBootApplication
public class EApplication {

    public static void main(String[] args) {
        Object o=new Object();
        SpringApplication.run(EApplication.class, args);
    }

}

1
2
3
4
5
6
7
8
9
10
11

4.如果报这个异常

5.在pom.xml添加如下依赖

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>

1
2
3
4
5
6

方式2：创建Java类来配置Swagger设置

1.在pom.xml添加依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
<!--        导入swagger-ui依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

1
2
3
4
5
6
7
8
9
10
11
12

2.创建Swagger的Java配置类(可以在配置类添加@EnableSwagger2注解，也可以在启动器类上加这个注解！)

/**swagger2配置
 * @author： wxh
 * @version：v1.0
 * @date： 2022/09/22 20:04
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket webApiConfig(){
        //添加head参数start
        ArrayList<Parameter> pars = new ArrayList<>();
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name("userId")
                .description("用户Id")
                .defaultValue("1")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(tokenPar.build());

        ParameterBuilder tmpPar = new ParameterBuilder();
        tmpPar.name("userTempId")
                .description("临时用户ID")
                .defaultValue("1")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(tmpPar.build());

        //添加head参数end

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //可以测试请求头中：输入token
                .apis(RequestHandlerSelectors.basePackage("com.gg.zhschool.controller"))
                //.apis(RequestHandlerSelectors.withClassAnnotation(ApiOperation.class))
                //过滤掉admin路径下的所有页面
                //.paths(Predicates.and(PathSelectors.regex("/sms/.*")))
                //过滤掉所有error或error.*页面
                //.paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build()
                .globalOperationParameters(pars);
    }

    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("网站-API文档")
                .description("本文档描述了网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("itfuture","http://www.baidu.com","itfuture03@163.com"))
                .build();
    }

    private ApiInfo adminApiInfo(){

        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("atguigu", "http://atguigu.com", "512111559@qq.com"))
                .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

3.在启动类添加注解@EnableSwagger2（如果在配置类已经加过则跳过此步）

@SpringBootApplication
@EnableSwagger2
public class ZhSchoolApplication {

    public static void main(String[] args) {
        SpringApplication.run(ZhSchoolApplication.class, args);
    }

}

1
2
3
4
5
6
7
8
9
10

---

然后启动项目，在浏览器输入：http://localhost:8080/swagger-ui.html

二、swagger权限验证、安全控制

当我们使用swagger，进行文档管理的时候，担心文档暴露(暴露接口)不安全时。

可采用两种方式

1.环境权限配置

对swagger文档配置只在测试环境可访问，生产环境不可访问。

 @Profile({"dev","test"})
1

如以上配置，则只有在dev以及test环境有效，在生产环境不可访问。

2.账户权限配置

在1.9.0版本时,针对Swagger的资源接口,SwaggerBootstrapUi提供了简单的Basic认证功能。
如果是springboot项目可在yml文件配置

(1)在yml文件中配置

swagger:
  production: false
  basic:
    enable: true
    username: eSwagger
    password: 123456
1
2
3
4
5
6

以上分别为启用，并且用户名为eSwagger.密码为123456。

切记swagger.production 不可设置为true，否则将屏蔽所有资源

(2)在swaggerConfig中添加注解

@EnableSwaggerBootstrapUI
1

结果就是此时访问需要通过用户密码才可进行访问!

此时只能通过配置的正确用户名和密码来登录！否则无法进入！