1. 项目概述：为什么你的Swagger需要一把锁？

如果你用过Swagger UI，肯定对那个清爽的API文档界面印象深刻。它把后端接口的结构、参数、返回值都可视化地展示出来，前后端联调、测试的时候别提多方便了。但方便的另一面，就是风险。默认情况下，Swagger UI是没有任何访问控制的，只要知道地址，任何人都能打开、查看，甚至直接调用你的接口。想象一下，你的开发环境、测试环境，甚至是不小心暴露在公网上的预发布环境，里面的接口文档和调试工具就这么敞开着，这无异于把自家后院的钥匙插在门上。

我见过不少团队，图省事，直接把带Swagger的应用部署到了测试服务器，结果被扫描工具扫到，接口信息一览无余。轻则泄露业务逻辑，重则可能被恶意调用，造成数据污染甚至安全漏洞。所以，给Swagger加个访问密码，不是什么“高级功能”，而是一个合格开发者应该具备的基本安全意识。这就像你家的Wi-Fi，你不会设置一个空密码让邻居随便连吧？给Swagger加锁，也是同样的道理。

这个“锁”的核心目标很简单：在访问Swagger UI页面时，弹出一个登录框，要求输入正确的用户名和密码，验证通过后才能看到文档内容。实现方式多种多样，从最简单的Spring Security基础认证，到整合公司统一的单点登录，再到利用网关层做统一的访问控制，都是可行的路径。今天，我就以最常用、最直接的Spring Boot + Spring Security方案为例，带你从头到尾实现一遍，并分享几个我踩过坑才总结出来的配置技巧和避坑指南。

2. 核心方案选型与设计思路

给Swagger加访问控制，听起来简单，但具体怎么做，取决于你的技术栈、项目阶段和安全要求。不同的方案，复杂度和适用场景完全不同。

2.1 主流方案对比与选型理由

在动手之前，我们先理清几种常见的实现路径：

1. 应用层拦截（本次详解）：在Spring Boot应用内部，通过Spring Security等安全框架，对访问/swagger-ui/**、/v3/api-docs/**等路径的请求进行拦截和认证。这是最经典、最可控的方式。
2. 网关层统一管控：如果项目使用了API网关（如Spring Cloud Gateway, Nginx），可以在网关层面配置针对Swagger路径的访问控制，比如Basic Auth、IP白名单、或与统一认证中心对接。这种方式将安全与业务解耦，适合微服务架构。
3. 容器/服务器层面控制：在Tomcat、Nginx等Web服务器或Docker容器中配置访问限制。这种方式更底层，不依赖应用代码，但灵活性稍差。
4. Swagger原生配置（有限）：Swagger UI本身提供了一些简单的安全配置选项，但通常功能较弱，难以满足复杂的认证需求。

为什么我首选Spring Security方案？对于大多数处于开发或测试阶段的单体或小型微服务Spring Boot项目来说，在应用内集成Spring Security是最快、最直接、学习成本最低的选择。它不需要引入额外的中间件，配置集中，调试方便，并且能与Spring Boot生态无缝集成。我们今天的目标是快速解决问题，所以这个方案最合适。

2.2 技术栈与依赖确认

我们的演示环境基于以下技术栈，这也是目前Java领域最主流的组合：

• Spring Boot: 2.7.x 或 3.x.x (两者配置有细微差异，下文会指出)
• Spring Security: 5.x 或 6.x (与Spring Boot版本对应)
• SpringDoc OpenAPI: 1.7.x (用于替代老旧的Springfox Swagger)
• Java 8+

这里特别强调一下SpringDoc OpenAPI。如果你还在用springfox-swagger2，我强烈建议你迁移到SpringDoc。它不仅支持更新的OpenAPI 3.0规范，而且与Spring Boot 3+兼容性更好，社区活跃。我们接下来的配置也基于SpringDoc。

Maven核心依赖如下：

<!-- SpringDoc OpenAPI (Swagger UI) --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.7.0</version> <!-- 请检查最新版本 --> </dependency> <!-- Spring Security --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> </dependency>

只要加入这两个依赖，你的项目就具备了提供Swagger UI和基础安全认证的能力。

2.3 安全设计要点

在设计时，我们需要明确几个关键点：

• 保护哪些路径？至少要保护Swagger UI的HTML页面路径（通常是/swagger-ui.html或/swagger-ui/index.html）和API文档JSON的提供路径（/v3/api-docs及其子路径）。
• 认证方式？我们采用最简单的HTTP Basic认证。用户在浏览器访问Swagger页面时，会弹出一个原生登录框。
• 用户从哪里来？为了演示，我们在内存中配置一个固定的用户名和密码。在实际生产或测试环境中，你应该从数据库或配置中心读取用户信息。
• 其他接口是否需要保护？这是一个重要的决策点。通常，我们只希望给Swagger加密码，而业务API接口（如/api/**）在开发测试环境可能不需要认证，或者使用另一套Token机制。我们需要在Spring Security的配置中精确区分这两类路径。

3. 一步步实现Swagger密码访问控制

理论清晰了，我们开始动手。我会按照从配置到验证的顺序，详细说明每一步。

3.1 基础安全配置类

首先，创建一个Spring Security的配置类。这是整个功能的核心。

import org.springframework.context.annotation.Bean; 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.core.userdetails.User; import org.springframework.security.core.userdetails.UserDetails; import org.springframework.security.core.userdetails.UserDetailsService; import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder; import org.springframework.security.crypto.password.PasswordEncoder; import org.springframework.security.provisioning.InMemoryUserDetailsManager; import org.springframework.security.web.SecurityFilterChain; import static org.springframework.security.config.Customizer.withDefaults; @Configuration @EnableWebSecurity public class SwaggerSecurityConfig { /** * 配置安全过滤链，定义哪些路径需要保护，哪些可以放行。 * 这是Spring Security 5.7+ / Spring Boot 2.7+ 推荐的Lambda DSL配置风格，更简洁。 */ @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(authz -> authz // 1. 精确匹配Swagger UI相关的资源路径，要求认证 .requestMatchers("/swagger-ui.html").authenticated() .requestMatchers("/swagger-ui/**").authenticated() .requestMatchers("/v3/api-docs").authenticated() .requestMatchers("/v3/api-docs/**").authenticated() // 2. 放行Swagger UI所需的静态资源（CSS, JS等） .requestMatchers("/webjars/**", "/swagger-resources/**").permitAll() // 3. 放行应用自身的健康检查、错误页面等公共端点（按需配置） .requestMatchers("/actuator/health", "/error").permitAll() // 4. 你的业务API路径，这里示例为全部放行。实际请根据需求调整。 .requestMatchers("/api/**").permitAll() // 5. 其他所有请求，默认要求认证（更安全）。如果只想保护Swagger，可以改为.permitAll() .anyRequest().authenticated() ) // 启用HTTP Basic认证。访问受保护路径时，浏览器会弹出登录框。 .httpBasic(withDefaults()) // 暂时禁用CSRF，因为Swagger UI的一些操作（如Try it out）会触发POST请求，CSRF保护会拦截它们。 // 注意：在生产环境中，需要更完善的CSRF处理策略。 .csrf(csrf -> csrf.disable()); return http.build(); } /** * 配置一个内存用户详情服务，用于演示。 * 实际项目中应替换为从数据库查询的UserDetailsService。 */ @Bean public UserDetailsService userDetailsService(PasswordEncoder passwordEncoder) { UserDetails user = User.builder() .username("admin") // 自定义用户名 .password(passwordEncoder.encode("swagger@123")) // 自定义密码，必须加密 .roles("SWAGGER_ADMIN") // 角色，可用于更细粒度的控制 .build(); return new InMemoryUserDetailsManager(user); } /** * 密码编码器。必须配置，用于对内存中的密码进行加密。 * 这里使用BCrypt，这是目前推荐的安全哈希算法。 */ @Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } }

关键点解析：

1. requestMatchers：用于匹配请求路径。顺序很重要，更具体的规则应该放在前面。
2. .authenticated()：表示匹配的路径需要认证（登录）后才能访问。
3. .permitAll()：表示匹配的路径允许所有人直接访问，无需认证。
4. /webjars/**和/swagger-resources/**：这是Swagger UI前端页面加载CSS、JavaScript等静态资源的路径。必须放行，否则即使登录成功，Swagger页面也无法正常加载样式和功能。
5. CSRF禁用：这是一个权衡。Swagger UI的“Execute”按钮会发送POST/PUT/DELETE请求，如果开启CSRF，需要额外处理Token，会使演示变复杂。在纯内部开发/测试环境，可以暂时禁用。若用于稍公开的环境，建议研究如何集成CSRF Token。

3.2 集成SpringDoc OpenAPI配置

接下来，我们配置SpringDoc，确保它能与Spring Security共存，并且能正确找到受保护的API文档端点。

创建一个配置类来定制SpringDoc：

import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Info; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class OpenApiConfig { @Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title("你的项目API文档") .version("1.0") .description("这是一个受保护的Swagger文档，需要登录访问。")); } }

这个配置不是安全必需的，但它能让你的Swagger文档页面标题和描述更友好。

一个至关重要的补充配置（解决常见空白页问题）：Spring Security默认会为所有请求添加一些安全头部，有时会干扰Swagger UI的运行。如果你发现登录后Swagger页面是空白的，或者控制台有CORS/Content Security Policy错误，可以在SecurityFilterChain配置中添加以下内容：

// 在 http.httpBasic(withDefaults()) 之后添加 .headers(headers -> headers .contentSecurityPolicy(csp -> csp .policyDirectives("script-src 'self' 'unsafe-inline' 'unsafe-eval'; object-src 'self';") ) .frameOptions(frame -> frame.sameOrigin()) // 允许同源iframe嵌入 )

这段配置放宽了内容安全策略，允许Swagger UI所需的行内脚本执行。

3.3 验证与访问

完成以上配置后，启动你的Spring Boot应用。

1. 访问Swagger UI：打开浏览器，输入http://localhost:8080/swagger-ui.html(或你的应用上下文路径)。
2. 弹出登录框：此时浏览器会弹出一个标准的HTTP Basic认证对话框，要求输入用户名和密码。
3. 输入凭证：输入我们在UserDetailsService中配置的用户名（admin）和密码（swagger@123）。
4. 成功访问：验证通过后，你将正常看到Swagger UI界面，所有API文档一览无余。

注意：如果你在登录后看到Swagger页面，但API列表处显示“Failed to load API definition”或“Fetch error”，并指向/v3/api-docs，这通常意味着/v3/api-docs这个路径没有被正确纳入保护或放行规则。请回头仔细检查SecurityFilterChain中requestMatchers对/v3/api-docs和/v3/api-docs/**的配置，确保它们被.authenticated()了。因为Swagger UI页面本身和获取JSON数据的请求是分开的，两者都需要认证。

4. 高级配置与生产级考量

上面的配置能跑起来，但离“好用”和“安全”还差几步。下面分享几个进阶配置点。

4.1 从配置文件读取凭证

把用户名密码硬编码在Java代码里是极不推荐的。我们应该放到application.yml或application.properties中。

application.yml配置：

swagger: auth: username: admin password: '@swagger123#' # 包含特殊字符时，用单引号包裹

修改UserDetailsService：

import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class SecurityConfig { @Value("${swagger.auth.username}") private String swaggerUsername; @Value("${swagger.auth.password}") private String swaggerPassword; @Bean public UserDetailsService userDetailsService(PasswordEncoder passwordEncoder) { UserDetails user = User.builder() .username(swaggerUsername) .password(passwordEncoder.encode(swaggerPassword)) // 密码仍需加密 .roles("SWAGGER_USER") .build(); return new InMemoryUserDetailsManager(user); } // ... 其他Bean定义 }

4.2 区分环境：仅在某些环境启用密码

我们可能只想在测试、预发布环境加密码，本地开发环境则希望直接访问。可以通过Profile和条件化配置来实现。

方案一：使用Profile创建两个不同的安全配置类，用@Profile注解标记。

@Configuration @Profile("!dev") // 非dev环境生效 @EnableWebSecurity public class ProdSwaggerSecurityConfig { // 包含完整密码保护的配置 } @Configuration @Profile("dev") // 仅dev环境生效 @EnableWebSecurity public class DevSecurityConfig { @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(authz -> authz .anyRequest().permitAll() // 开发环境全部放行 ) .csrf(csrf -> csrf.disable()); return http.build(); } }

启动应用时，通过--spring.profiles.active=dev来激活dev配置。

方案二：通过配置属性控制在配置文件中增加一个开关。

swagger: auth: enabled: true username: admin password: secret

然后在Java配置中，根据这个开关动态决定是否配置认证：

@Value("${swagger.auth.enabled:false}") private boolean swaggerAuthEnabled; @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception throws Exception { if (swaggerAuthEnabled) { // 应用带认证的配置 http.authorizeHttpRequests(authz -> authz .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").authenticated() // ... 其他规则 ).httpBasic(withDefaults()); } else { // 放行Swagger相关路径 http.authorizeHttpRequests(authz -> authz .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll() // ... 其他规则 ); } http.csrf(csrf -> csrf.disable()); return http.build(); }

4.3 整合数据库或LDAP认证

内存用户只适合演示。真实项目用户信息通常存在数据库或LDAP中。你需要实现一个从数据库查询的UserDetailsService。

@Service public class DatabaseUserDetailsService implements UserDetailsService { @Autowired private UserRepository userRepository; // 假设你的用户仓库 @Override public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException { // 1. 从数据库根据username查询用户实体 UserEntity userEntity = userRepository.findByUsername(username) .orElseThrow(() -> new UsernameNotFoundException("用户不存在: " + username)); // 2. 将数据库中的角色字符串转换为Spring Security的GrantedAuthority List<GrantedAuthority> authorities = userEntity.getRoles().stream() .map(role -> new SimpleGrantedAuthority("ROLE_" + role)) .collect(Collectors.toList()); // 3. 构建并返回Spring Security的UserDetails对象 return new org.springframework.security.core.userdetails.User( userEntity.getUsername(), userEntity.getPassword(), // 数据库中的密码应该是加密存储的 authorities ); } }

然后在安全配置类中，注入这个自定义的UserDetailsServiceBean即可。

5. 常见问题排查与实战技巧

即使按照步骤操作，你也可能会遇到一些坑。这里我整理了最常见的问题和解决方法。

5.1 问题速查表

5.2 实操心得与避坑指南

1. 路径匹配的优先级与精确性：Spring Security的匹配规则是从上到下执行，第一个匹配的规则生效。一定要把最具体、最特殊的路径（如/swagger-ui.html）放在前面，把最通用的路径（如/api/**）放在中间，把anyRequest()放在最后。顺序错了，可能会导致规则覆盖，出现意想不到的放行或拦截。

2. 静态资源放行是必须的：这一点我反复强调，因为它太容易出错。Swagger UI不是一个简单的HTML，它依赖大量前端资源。只保护/swagger-ui.html而没放行/webjars/**，结果就是看到一个没有样式、没有功能的“裸”页面，或者根本加载不出来。务必在配置中检查这两条放行规则。

3. 密码加密是强制要求：从Spring Security 5开始，{noop}前缀（表示无加密）虽然还能用，但控制台会出警告。使用BCryptPasswordEncoder是标准做法。在内存中配置用户时，密码必须通过passwordEncoder.encode(“明文密码”)处理后再存储。否则，认证时会因为编码不匹配而失败。

4. 善用浏览器开发者工具：遇到问题时，第一时间打开浏览器的“网络”(Network)面板。查看访问swagger-ui.html、v3/api-docs以及各类.js、.css文件时的HTTP状态码。401代表未认证，403代表无权限，404代表路径错误。根据状态码能快速定位问题方向。

5. 环境隔离是最佳实践：永远不要用一套安全配置走天下。通过Spring Profiles或条件化Bean，为本地开发、测试环境、生产环境设置不同的安全策略。本地可以完全开放，测试环境加简单密码，生产环境则可能结合OAuth2、JWT等更复杂的方案，或者直接禁用Swagger。

6. 关于CSRF的取舍：在前后端分离且使用Token（如JWT）认证的架构中，CSRF的风险相对较低，因为标准做法不会将Token存在Cookie中。如果你的Swagger仅用于内部调试，且业务API也是Token认证，禁用CSRF以简化Swagger操作是常见的做法。但这需要你充分理解CSRF的风险和你的应用架构。