swagger配置使用及安全方案

1.swagger的依赖

pom依赖，这是针对swagger2的

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

pom依赖，这是针对swagger3的

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.2.31</version>
</dependency>

2.swagger配置

swagger2配置需要添加两个注解，包括@EnableSwagger2和@Configuration

 此处需要留意，如果项目是基于springmvc，需要手动添加配置注册swagger，帮助mvc找到swagger-ui.html对应的文件

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

 swagger3配置需要添加一个配置类

上图中涉及了三个子对象，起到的作用不同：

components主要是用于配置用户的token认证校验 Components对象里面包含Map<String, SecurityScheme>结构的securitySchemes对象

public OpenAPI components(Components components) {
    this.components = components;
    return this;
}

// 1.1.securitySchemes对象包含key和SecurityScheme对象，SecurityScheme对象里面包含type，name，in，description等参数字段
public Components addSecuritySchemes(String key, SecurityScheme securitySchemesItem) {
    if (this.securitySchemes == null) {
       this.securitySchemes = new LinkedHashMap();
    }
    this.securitySchemes.put(key, securitySchemesItem);
    return this;
}

 info主要用于swagger页面的标题和版本确认，Info对象包含title，version和description字段

public OpenAPI info(Info info) {
    this.info = info;
    return this;
}

externalDocs用于标题下面的链接，ExternalDocumentation内部又包含description和url字段

public OpenAPI externalDocs(ExternalDocumentation externalDocs) {
    this.externalDocs = externalDocs;
    return this;
}

3.启动类配置，无论是swagger2还是swagger3，都需要配置

如果项目不存在springMVC配置，仍然报404，肯定是接口地址有问题，例如本项目中，路由地址添加了context-path，如果添加了也要用contact拼接上去

ps：此处要特别注意，如果启动成功，但swagger报404，肯定是接口地址有问题，例如本项目中，路由地址添加了context-path

4.安全问题---解决方案

项目在进行安全扫描时，swagger是很容易收到安全攻击的，因此需要设计一套针对与swagger的安全访问权限，如test表示test环境可以被访问，其他环境不可以被访问

如上图所示，@Profile和@EnableSwaggerBootstrapUI都能够配置swagger访问权限。二者单一使用即可，如需组合使用，需要注意注解的顺序

二者比较而言，@Profile环境权限配置权限较大，故需要注意注解的顺序

@Profile({"test"})//环境权限配置，该权限较大，无论如何都会优先执行第一个权限
@EnableSwaggerBootstrapUI

当使用@EnableSwaggerBootstrapUI注解时，需要在yml文件中配置swagger的访问账号密码

swagger:
#  不可设置为true，否则将屏蔽所有资源
  production: false
  basic:
    enable: true
    username: root
    password: 123456

如上图所示采用组合方式的权限访问，首先确认环境是否正确，再确认密码正确，全部正确才可以进入访问。如果环境校验不通过，则不会出现输入密码的场景