SpringSecurity结合knife4j实现swagger文档

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驱动开发中不可或缺的一环。