Spring Security与Knife4j（原SwaggerBootstrapUi）的集成旨在为基于Spring Boot的应用程序提供一套既安全又美观的API文档解决方案。Spring Security负责确保API接口的安全访问控制，而Knife4j则专注于提升Swagger UI的用户体验，使开发者和API使用者能更高效地浏览、测试及理解RESTful API。
1. 环境准备
首先，确保你的项目是一个基于Spring Boot的应用，并且已经集成了Spring Security与Swagger。Spring Boot版本建议使用2.x及以上，同时引入Swagger相关依赖，通常是 springfox-boot-starter，以及Knife4j的UI增强库 knife4j-spring-boot-starter。
2. 添加依赖
在 pom.xml中添加以下依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version> <!-- 根据实际版本调整 -->
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version> <!-- 根据实际版本调整 -->
</dependency>
3. 配置Spring Security
为了允许Swagger UI绕过Spring Security的认证机制，你需要在Spring Security配置类中添加相应的规则。这通常涉及到重写 WebSecurityConfigurerAdapter的 configure方法，以排除Swagger相关的路径。
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
@Override
public void configure(WebSecurity web) throws Exception {
web.ignoring().antMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-resources/**");
}
// 其他安全配置...
}
4. 配置Swagger与Knife4j
接下来，在Spring Boot的主配置类或一个独立的配置类中启用Swagger，并进行Knife4j的相关配置。
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("你的应用名称")
.description("API文档描述")
.version("1.0.0")
.build();
}
}
5. 访问Swagger UI
完成上述步骤后，启动你的Spring Boot应用，然后访问 http://localhost:8080/swagger-ui.html（假设端口为8080），你应该能看到由Knife4j提供的增强版Swagger UI界面。在这里，你可以浏览所有开放的API接口，执行在线测试，查看请求参数和响应示例等。
分析说明表
| 阶段 | 操作内容 | 目标 |
|---|---|---|
| 环境准备 | 确认项目基础 & 引入依赖 | 准备集成所需的开发环境 |
| 添加依赖 | 在pom.xml中添加Swagger & Knife4j | 完成技术栈的集成准备 |
| Spring Security配置 | 配置安全路径豁免 | 确保Swagger UI可无鉴权访问 |
| Swagger配置 | 启用Swagger并自定义信息 | 生成API文档并美化展示 |
| 访问Swagger UI | 浏览和测试API | 验证集成效果与使用体验 |
总结
通过将Spring Security与Knife4j相结合，我们不仅能够为RESTful API提供强大的安全防护，还能保证API文档的易用性和可访问性，这对于API的设计、开发和维护来说至关重要。这种集成方式不仅提升了开发效率，也优化了API使用者的体验，是现代API驱动开发中不可或缺的一环。
