Swagger权限认证上：基于Apache Shiro

有很多文章提到，在生产环境中需要关闭Swagger功能，防止系统资源泄露。今天，我结合自己开发过程中的经验，分享一个只需几行代码便可实现让Apache Shiro接管Swagger认证和授权的方法。如果还有更好的方法，欢迎在文章末尾给我留言，一起交流。

初识Swagger

简单来说，Swagger是一个开放源代码的框架，旨在使用通用化的语言，让开发者和非开发者都能理解你设计的API是什么结构，有什么用途。API文档好比建筑蓝图，在建造房子时，必须按照蓝图的规格参数进行。

通常，一个软件项目会伴随着很多的API文档需要编写，当软件版本变更时，还需要修改所有的API文档细节(例如：请求地址，请求参数，返回值等等)。这是一件极具挑战性的工作。长期以来，工程师们一直在努力寻找一种标准化的流程/方法来解决API文档的设计，编写，测试和维护问题，Swagger就是在这样一种背景下诞生的。

Swagger为API文档的设计，开发，测试，维护提供了统一的解决方案。这极大的减轻了开发人员的工作负担。但随之而来的一个问题也会让人担心，通过Swagger UI提供统一的API文档阅览和测试，这会导致在生产环境下暴露系统资源。

我们并不希望所有人都可以查阅系统的API文档，就像不是所有人都有权限查看建筑蓝图一样。那么如何解决这一问题呢？

Apache Shiro接管Swagger权限认证

Swagger官方提供了6种认证和授权方式：basic-authentication、API密钥、bearer-authentication、Oauth 2.0、OpenID Connect Discovery和Cookie。但这几种方式在体验上效果都不好(当然，你也可以选择在生产环境中关闭Swagger的功能)。能不能有一种方式，让系统本身的权限认证体系接管Swagger的授权认证工作，让Swagger专注于自己擅长的领域呢？这就是本文要介绍的重点。

快速认识Apache Shiro

Apache Shiro™是一个功能强大且易于使用的Java安全框架，用于执行身份认证，授权，加密和会话管理。你可以轻松地将其集成到你的项目中，且不需要改动太多的代码。Shiro支持一个或多个可插拔的数据源，例如LDAP、JDBC、Active Directory等等，与此同时，Shiro还支持不同粒度的访问控制，如基于用户组，用户角色，资源权限等。

使用Shiro接管Swagger认证授权

首先，假定你已经在自己的项目中使用了Swagger，并且你的项目是基于Spring Boot 2.0进行构建的，同时使用Maven对项目的依赖进行管理。如果你的项目还未使用Swagger,请将下面代码配置到pom.xml文件中：

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

另外，请检查项目中是否加入了Shiro项目依赖，如果还未添加，请将下面代码配置到pom.xml文件中：

    org.apache.shiro
    shiro-core
    1.4.2


    org.apache.shiro
    shiro-ehcache
    1.4.0


    org.apache.shiro
    shiro-spring
    1.4.0

备注

shiro-core：Apache Shiro核心依赖包

shiro-ehcache：基于Ehcache实现的数据缓存依赖包

shiro-spring：Apache Shiro与Spring整合依赖包

配置Swagger

依赖就绪后，创建一个Swagger的配置文件并设置Swagger要扫描的包路径(通常是Controller所在的包)，API文档标题(title)，描述(description)，版本号(version)，联系方式(contact)以及证书名称（license）等等。下面是Swagger配置文件示例：

SwaggerConfiguration.java

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ramostear.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(
                        new ApiInfoBuilder()
                        .title("Apache Shiro & Swagger")
                        .description("使用Apache Shiro接管Swagger认证和授权")
                        .version("1.0.0")
                        .contact(
                                new Contact("树下魅狐",
                                        "https://www.ramostear.com",
                                        "[email protected]")
                        )
                        .license("The Apache License")
                        .build()
                );
    }
}

注意

除了使用@Configuration对配置类进行注解外，别将@EnableSwagger注解遗漏！

在Shiro中配置Swagger

如果你的项目已经使用Apache Shiro进行认证和授权工作，那么只需要在ShiroFilterFactoryBean的配置代码中加入对Swagger的过滤操作即可。你可以参照下面的代码进行配置：

ShiroConfiguration.java

@Configuration
public class ShiroConfiguration{
    
    @Bean
    public EhCacheManager ehCacheManager(){...}
    
    @Bean
    public CustomShiroRealm customShiroRealm(){...}
    
    @Bean
    public SecurityManager securityManager(){
        DefaultWebSecurityManager securityManager = new DefaultWebSecurityManager();
        securityManager.setCacheManager(ehCacheManager());
        securityManager.setRealm(customShiroRealm());
        return securityManager;
    }
    ...
    
    @Bean
    public ShiroFilterFactoryBean shiroFilterFactoryBean(SecurityManager securityManager){
        ShiroFilterFactoryBean filterFactoryBean = new ShiroFilterFactoryBean();
        filterFactoryBean.setSecurityManager(securityManager);
        Map filterChainDefinition = new LinkedHashMap<>();
        ...
            
        filterChainDefinition.put("/swagger-ui.html","authc");
        filterChainDefinition.put("/v2/**","authc");
        filterChainDefinition.put("/swagger-resources/**","authc");
        filterFactoryBean.setFilterChainDefinitionMap(filterChainDefinition);
        return filterFactoryBean;     
    }
    ....
}

补充

除了上述给出的配置方式外，你可以根据实际需要，配置更细粒度的权限，例如用户组，角色以及资源权限等等。

至此，如果你的项目原本使用了Apache Shiro框架，那么只需在原代码的基础上，增加三行配置代码，即可让Apache Shiro接管Swagger的认证和授权工作。

最后，通过实际项目来演示Apache Shiro接管Swagger认证和授权工作的效果：

说明

/admin/swagger请求页面嵌入了一个iframe,其地址为：/swagger-ui.html。具体代码如下：

swagger.html

    
        ...
    
    
        ...
        
        ...
    
    

当用户登录成功后，可以正常访问Swagger的API文档页面，当注销当前用户后，再次访问Swagger页面，系统会跳转到用户登录页面，要求验证用户身份。

---