Swagger正确打开方式（二）安全访问

安全访问主要分以下两种：

1.环境的安全隔离。swagger基本上把项目所有的请求接口都罗列出了，而且支持接口在线调试，所以线上环境不应该开启swagger接口功能，试想如果开启了swagger功能，哪位开发测试人员，通过swagger就可以任意访问线上接口了，这显然是不安全的。

2.接口调试访问权限认证。我们的很多接口都是需要登录后才能访问及操作，为了安全起见，用swagger也不能例外。

一、环境的安全隔离

swagger接口文档适用环境配置

进行swagger环境配置配置说明之前，本文主要简单介绍结合maven使用的环境管理方式，其他方式大同小异，无非是通过设置环境变量或者手动设置启动版本激活属性设置运行时配置参数，其实我理解的不管用什么方式，无非是达到动态配置spring.profiles.active属性的目的。

maven版本控制

想要通过maven进行项目环境变量管理，只需要在pom文件里面增加profiles配置项就好了，大概格式如下：

        
            pro
            
                pro
                8080
                false
            
        
         
            test
            
                test
                8080
                true
            
         
        
            local
            
                true
            
            
                localhost
                8089
                true
            
        
    

 其中包含activation的配置项为默认配置项,改选择默认为false，本地开发启动的时候会默认使用当前配置项；如果要修改默认选用配置，可以通过修改activation标签进行设置。当然你可以通过intellij idea右侧悬浮的mave工具栏选择进行设置，如下图：

添加号pom文件配置项后，在咋们的application.yml文件里面增加如下内容：

server:
  port: '@web.port@'
spring:
  profiles:
    active: '@label@'
swagger: 
    enable: '@swagger.enable@'

注：上述配置文件只是为了演示环境配置的简要配置，非系统运行的完整配置项。

这样项目启动时，spring就能够知道当前启用的配置环境变量了。

此时项目打包时只需要执行下面命令即可：

mvn package -Dmaven.test.skip -Plocalwin
# -Dmaven.test.skip 为打包的时候跳过执行单元测试
# -Plocal -P后面跟的就是我们pom文件里面的profile label标签

swagger 环境选择

做好上述操作后，只需要在咋们的SwaggerXComfig.java文件上加上对应配置项就好，这里swagger2和swagger3稍许有点不一样，swagger2格式如下：

@Configuration
@EnableSwagger2
@Profile({"local","test"})
// 这里设置的是开启swagger的环境，我这里设置的是只有本地环境和测试环境才开始swagger
// 或者使用下面个这是方式
// @ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
// swagger3为咋们配置项前缀，enable参数为咋们配置的属性值
public class Swagger2Config {
}

 上述方法swagger3好像是不起作用了，swagger3配置方式更为简单，只用在Docket里面设置enable属性就好：

@Configuration
public class Swagger3Config {

    @Value("${swagger.enable}")
    private boolean enable;

    @Bean
    public Docket createRestApi() {

        log.info("加载Swagger3");

        return new Docket(DocumentationType.OAS_30)
                // 是否启用swagger
                .enable(enable)
                .apiInfo(apiInfo()).select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
                .title("swagger3接口文档")
                .description("接口文档")
                .contact(new Contact("碧海燕鱼", "#", "[email protected]"))
                .version("0.1.0")
                .build();
    }
}

 环境配置好后，如果访问没有启用swagger环境的swagger服务大概结果如下：

二、接口调试访问权限认证

由于我们的大多数的接口都需要用户登录后，携带登录品质才可以正常访问，所以想要通过swagger调试这些登陆后才能访问的接口，我们则在swagger里增加登录令牌配置。

我们通过前面的配置，启动访问swagger样子如下：

我们需要增加登录令牌配置，这里配置swagger2和swagger3只需要在咋们的Swagger3Comfig.java配置文件上设置Docket的启动参数securitySchemes和securityContexts即可，完整配置文件如下：

@Configuration
public class Swagger3Config {

    @Value("${swagger.enable}")
    private boolean enable;
    /**
     * 安全方案
     * @return
     */
    private List securitySchemes() {
        List apiKeys = new ArrayList<>();
        // 在header请求头内增加Accept-Info请求信息，输入关键字为accessToken
        apiKeys.add(new ApiKey("Accept-Info","accessToken", "header"));
        return apiKeys;
    }

    /**
     * 请求体内容
     * @return
     */
    private List securityContexts() {
        List securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .build());
        return securityContexts;
    }

    private List defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Accept-Info",authorizationScopes));
        return securityReferences;
    }

    @Bean
    public Docket createRestApi() {

        log.info("加载Swagger3");

        return new Docket(DocumentationType.OAS_30)  // 文档版本
                .pathMapping("/")
                .enable(enable) // 是否开启swagger
                .apiInfo(apiInfo()).select() // 选择哪些接口作为swagger的doc发布
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 若果要设置所欲的request请求都收录到swagger文档中，只需设置.apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .protocols(new HashSet<>(Arrays.asList("http", "https")))   //支持的通讯协议集合
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger3接口文档")
                .description("接口文档")
                .contact(new Contact("碧海燕鱼", "#", "[email protected]"))
                .version("0.1.0")
                .build();
    }
}

修改号上述配置后，再运行项目，此时是这样的：

 可以看到接口顶部和接口后面对了一个小锁，点击小锁，点击小锁会出现录入请求令牌的弹框窗口

在弹出窗口输入框输入你的登录令牌就行，我这里key名称叫Accept-Info，是因为我接受请求头里包含很多前端封装的其他参数，token只是其中一个字段，所以我的value里面吧这个请求参数的json输入即可，这里你们根据自己的情况来就好。 

到此，swagger的接口安全访问已经做好了，欢迎评论区指正和补充。