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

我会带着你远行 2023-09-29 17:36 12阅读 0赞

#### 配置Swagger的两种方式以及swagger权限验证、安全控制 ####

*  前言
 *  一、springboot配置Swagger的两种方式
 *   *  方式1：使用配置文件来配置Swagger设置
     *  方式2：创建Java类来配置Swagger设置
 *  二、swagger权限验证、安全控制
 *   *  1.环境权限配置
     *  2.账户权限配置

## 前言 ##

**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>

**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'

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

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

**4.如果报这个异常**

![在这里插入图片描述][166c002f611645adba086e38da503dbe.png]  
**5.在pom.xml添加如下依赖**

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

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

**1.在pom.xml添加依赖**

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.9.2</version>
            </dependency>
    
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.9.2</version>
            </dependency>

**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();
        }
    
    }

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

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

--------------------

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

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

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

可采用两种方式

### 1.环境权限配置 ###

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

![在这里插入图片描述][6b84077237ed459f8260ae413820cda1.png]

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

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

### 2.账户权限配置 ###

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

(1)在yml文件中配置

swagger:
      production: false
      basic:
        enable: true
        username: eSwagger
        password: 123456

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

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

(2)在swaggerConfig中添加注解

@EnableSwaggerBootstrapUI

![在这里插入图片描述][7d343e61c44141768c474cccc51e8c43.png]

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

![在这里插入图片描述][be214f67484c41ed8bbc5a292f8a38f4.png]  
此时只能通过配置的正确用户名和密码来登录！否则无法进入！

[166c002f611645adba086e38da503dbe.png]: https://img-blog.csdnimg.cn/166c002f611645adba086e38da503dbe.png
[6b84077237ed459f8260ae413820cda1.png]: https://img-blog.csdnimg.cn/6b84077237ed459f8260ae413820cda1.png
[7d343e61c44141768c474cccc51e8c43.png]: https://img-blog.csdnimg.cn/7d343e61c44141768c474cccc51e8c43.png
[be214f67484c41ed8bbc5a292f8a38f4.png]: https://img-blog.csdnimg.cn/be214f67484c41ed8bbc5a292f8a38f4.png