为什么需要关注Swagger UI的访问路径？

在Spring Boot项目中，Swagger UI默认通过/swagger-ui.html路径提供访问。但在实际开发中，直接使用默认路径可能带来以下问题：

1. 安全性风险：生产环境中暴露默认路径可能被恶意扫描
2. 路径冲突：与其他路由规则冲突导致访问失败
3. 多环境管理：不同环境需要不同的访问策略

基础配置方法

1. 添加Maven依赖

首先确保项目中已包含Swagger相关依赖：

xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>

2. 基础配置类

创建Swagger配置类：

java
@Configuration
@EnableSwagger2
public class SwaggerConfig {

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build();
}

}

高级路径配置技巧

1. 自定义基础路径

通过springfox.documentation.swagger.v2.path属性修改默认路径：

yaml springfox: documentation: swagger: v2: path: /api-docs

此时Swagger UI的访问路径将变为：http://域名:端口/api-docs/swagger-ui.html

2. 结合应用上下文路径

如果项目配置了server.servlet.context-path，需要特别注意路径拼接问题：

yaml server: servlet: context-path: /myapp

此时完整访问路径为：http://域名:端口/myapp/swagger-ui.html

3. 多环境差异化配置

建议在不同环境中采用不同策略：

java
@Profile("!prod")
@Configuration
@EnableSwagger2
public class DevSwaggerConfig {
// 开发环境详细配置
}

@Profile("prod")
@Configuration
public class ProdSwaggerConfig {
// 生产环境可能完全禁用或添加安全校验
}

安全加固建议

1. 添加访问限制：
   java @Bean public SecurityFilterChain swaggerSecurity(HttpSecurity http) throws Exception { http.authorizeRequests() .antMatchers("/swagger-ui/**").hasRole("ADMIN") .and().httpBasic(); return http.build(); }

2. 生产环境禁用：
   yaml spring: profiles: prod swagger: enabled: false

3. 自定义登录校验：可通过拦截器实现动态token验证

常见问题排查

问题1：404无法访问
- 检查@EnableSwagger2注解是否添加
- 确认没有@EnableWebMvc冲突

问题2：静态资源加载失败
- 确保正确配置资源处理：
java @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/swagger-ui/**") .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/"); }

问题3：路径冲突
- 使用PathSelectors.regex()精确控制API扫描范围

最佳实践总结

1. 开发环境使用详细文档，生产环境限制访问或完全禁用
2. 结合项目上下文路径设计完整访问URL
3. 为Swagger UI配置单独的安全策略
4. 使用Profile实现环境差异化配置
5. 定期检查Swagger依赖版本以修复潜在漏洞

通过合理配置Swagger UI路径，既能保证开发效率，又能避免安全风险，是Spring Boot项目开发中值得重视的细节。