解锁Swagger鉴权

在开发过程中，Swagger 是一个非常流行的 API 文档生成工具，它不仅可以帮助开发者设计、构建、记录 RESTful API，还能通过其交互式的 UI 改善前后端开发者的沟通效率。然而，在实际生产环境中，暴露未加保护的 API 文档可能会带来安全风险。因此，为 Swagger 接口添加鉴权功能，成为了一个重要的需求。

在本文中，我们将详细讨论如何在 Java 应用中为 Swagger UI 实现鉴权功能，确保只有授权用户才能访问 API 文档。

1. 为什么需要为 Swagger 添加鉴权？

Swagger UI 非常方便，开发者和测试人员可以通过它直接发送请求，测试 API。但这也意味着任何知道 URL 的人都可以查看你的 API 结构和细节，甚至测试各种输入。在公网或者非安全环境下，这可能导致安全漏洞。

2. 使用 Spring Security 添加鉴权

在 Java 开发中，Spring Security 是实现安全控制的强大框架，它可以很方便地与 Swagger 集成来提供鉴权。

2.1 引入必要的依赖

首先，确保你的项目中已经包含了 Swagger 和 Spring Security 的依赖。以下是在 Maven pom.xml 文件中添加的示例：

<dependencies>
    <!-- Swagger -->
    <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>

    <!-- Spring Security -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
</dependencies>

2.2 配置 Spring Security

接下来，我们需要配置 Spring Security 来保护 Swagger UI 路径。创建一个配置类 WebSecurityConfig 继承 WebSecurityConfigurerAdapter：

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
@EnableWebSecurity
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/swagger-ui.html", "/swagger-resources/**", "/v2/api-docs", "/webjars/**")
                .authenticated()
            .and()
            .formLogin()
            .and()
            .httpBasic();
    }
}

这段代码配置了 Spring Security 以保护 Swagger 相关的 URL。任何尝试访问这些 URL 的用户都需要通过登录认证。

2.3 添加用户认证信息

在 WebSecurityConfig 中，我们还需要配置用户信息，可以使用内存存储的方式：

import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;

@Override
protected void configure(AuthenticationManagerBuilder auth) throws Exception {
    auth.inMemoryAuthentication()
        .withUser("user")
        .password(passwordEncoder().encode("password"))
        .roles("USER");
}

@Bean
public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
}

这里我们创建了一个用户名为 user，密码为 password 的用户，这些信息通常应该根据实际情况从数据库或其他服务获取。

3. 测试和验证

启动你的 Spring Boot 应用，访问 http://localhost:8080/swagger-ui.html，你应该会被重定向到登录页面。输入正确的用户名和密码后，你将能够访问 Swagger UI。

4. 总结

通过上述步骤，你可以为你的 Swagger UI 添加基本的鉴权功能，增强 API 文档的安全性。这不仅可以防止未经授权的访问，还可以通过日志记录访问者信息来帮助监控和审计。