springboot 集成 Knife4j 插件 集Swagger2 和 OpenAPI3为一体一体的增强解决方案

系列文章目录

---

---

前言

Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案
springboot 集成官网文档地址

---

一 spring-boot版本和Knife4j 版本对应

Spring Boot版本及其对应的Knife4j版本兼容推荐

二、代码实现

1.引入Knife4j 依赖

代码如下（示例）：

<!--引入Knife4j的官方start包,该指南选择Spring Boot版本<3.0,开发者需要注意-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

2. 配置依赖 可以通过yaml 或者手动配置类

通过yaml配置的话-> 最低版本 2.0.6 版本后,只需要在配置文件中配置knife4j.enable=true即可不在使用注解注意：要使用Knife4j提供的增强，knife4j.enable=true必须开启

代码如下（示例）：

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "dockerBean")
    public Docket dockerBean() {
        //指定使用Swagger2规范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                //描述字段支持Markdown语法
                .description("# Knife4j RESTful APIs")
                .termsOfServiceUrl("https://doc.xiaominfo.com/")
                .contact("xiaoymin@foxmail.com")
                .version("1.0")
                .build())
                //分组名称
                .groupName("用户服务")
                .select()
                //这里指定Controller扫描包路径 可以指定某一个包 是绝对路径
                //.apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
                // 扫面所有包
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

3. 增强模式

1. 增强模式官方地址
2. 权限控制 生产的时候关闭 需要屏蔽所有Swagger的相关资源

4. 如果集成了SpringSecurity 安全框架 开放静态资料 如下

代码如下

  @Override
    protected void configure(HttpSecurity httpSecurity) throws Exception
    {
        httpSecurity
                // CSRF禁用，因为不使用session
                .csrf().disable()
                // 认证失败处理类
                .exceptionHandling().authenticationEntryPoint(unauthorizedHandler).and()
                // 基于token，所以不需要session
                .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS).and()
                // 过滤请求
                .authorizeRequests()
                // 对于登录login 注册register 验证码captchaImage 允许匿名访问
                .antMatchers("/login", "/register", "/captchaImage").anonymous()
                .antMatchers(
                        HttpMethod.GET,
                        "/",
                        "/*.html",
                        "/**/*.html",
                        "/**/*.css",
                        "/**/*.js",
                        "/profile/**",
                        "/doc.html",
                        "/swagger-ui/**"
                ).permitAll()
                .antMatchers("/swagger-ui.html").anonymous()
                .antMatchers("/swagger-resources/**").anonymous()
                .antMatchers("/webjars/**").anonymous()
                .antMatchers("/**/api-docs/**").anonymous()
                .antMatchers("/druid/**").anonymous()
                // 除上面外的所有请求全部需要鉴权认证
                .anyRequest().authenticated()
                // 使用自定义的 accessDecisionManager
                .accessDecisionManager(accessDecisionManager())
                .and()
                // 添加未登录与权限不足异常处理器
                .exceptionHandling()
                .accessDeniedHandler(restfulAccessDeniedHandler)
                .authenticationEntryPoint(restAuthenticationEntryPoint)
                .and()
                .headers().frameOptions().disable();
        httpSecurity.logout().logoutUrl("/logout").logoutSuccessHandler(logoutSuccessHandler);
        // 添加JWT filter
        httpSecurity.addFilterBefore(authenticationTokenFilter, UsernamePasswordAuthenticationFilter.class);
    }

5. 具体使用

访问页面 http://ip:port/server.servlet.context-path/doc.html

1. 搜索接口
   
2. 设置全局参数 主要用来 例如后台全局token参数等.提供该功能主要是方便开发者进行调试
   链接地址
   

---

总结

该插件 作用如下

• 基础ui组件(自定义文档、动态参数调试、I18n、接口排序、导出文档等)
• 基于Springfox框架+Swagger2规范的自动注入starter
• 基于Springdoc-openapi+OAS3规范的自动注入starter
• 提供对主流网关组件的统一聚合OpenAPI接口文档的解决方案