knife4j的配置使用

knife4j 是一项后端接口文档技术，能够很方便后端开发。

本文介绍knife4j 的使用配置。

pom文件导入依赖

适用于springboot3 的版本

        <!--添加Knife4j依赖-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.5.0</version>
        </dependency>

注意，knife4j 有很多配置方法，注意依赖的名字。不同的依赖，配置有所不同，比如还有下面两种依赖：

第一种依赖
注意这个是openapi2
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.2.0</version>
</dependency>


第二种依赖
<dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
     <version>2.0.1</version>
</dependency>

本人配置依赖为最上面的那个！！！knife4j-openapi3-jakarta-spring-boot-starter 4.5.0

新建knife4j 的配置类

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        // 标题
                        .title("knife4j")
                        // 描述
                        .description("knife4j接口文档")
                        // 版本
                        .version("v1") 
                        //可以自己设定自己的名字和邮箱还有URL地址
                        .contact(new Contact().name("name").email("email"))
                        .license(new License().name("Apache 2.0")));
    }
}

修改yml文件

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    # 排序方式为首字母
    tags-sorter: alpha
    # 使用增强order属性进行排序，或者不设置该参数( @ApiOperationSupport(order = n)直接生效)
    operations-sorter: order
  api-docs:
    path: /v3/api-docs
  group-configs:
    #组名可以自己设置
    - group: 'default'
      paths-to-match: '/**'
      # controller所在包
      packages-to-scan: com.knifej.test.controller

# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

排除knife4j的文档访问地址

@Configuration
@Slf4j
public class InterceptorConfig implements WebMvcConfigurer {
 
    @Resource
    private LoginInterceptor loginInterceptor;
 
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(loginInterceptor)
                .addPathPatterns("/**")  // 其他接口需要token验证
                //排除knife4j的接口文档页面
                .excludePathPatterns("/**.html")
                .excludePathPatterns("/v3/api-docs/**")
                //排除登录注册页面
                .excludePathPatterns("/login")
                .excludePathPatterns("/register");
 
    }
 
}

启动springboot项目

最后访问 IP:Port/doc.html 即可

======================================================================

以下为2024-7-9补充

springboot 2 版本 + jdk 8 的配置

导入依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.2.0</version>
</dependency>

配置类

(注意不能漏掉@EnableSwagger2WebMvc 注解！！！！)

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
    
    //配置Swagger2的Docket的Bean实例
    @Bean(value = "defaultApi2")
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // apiInfo()：配置 API 的一些基本信息，比如：文档标题title，文档描述description，文档版本号version
                .apiInfo(apiInfo())
                // select()：生成 API 文档的选择器，用于指定要生成哪些 API 文档
                .select()
                // apis()：指定要生成哪个包下的 API 文档
               .apis(RequestHandlerSelectors.basePackage("com.jasper.user_center.controller"))
                // paths()：指定要生成哪个 URL 匹配模式下的 API 文档。这里使用 PathSelectors.any()，表示生成所有的 API 文档。
                .paths(PathSelectors.any())
                .build();
    }
    //文档信息配置
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("swagger_knife4j")
                // 文档描述信息
                .description("在线API文档")
                // 文档版本号
                .version("1.0")
                .build();
    }
}

 不用配置application.yml ，启动项目访问即可

如果配置了，jdk是8的话 ，springboot 版本为2 ， 配置如下（与高版本的jdk和knife4j的拦截配置有点不同）：

@Configuration
@Slf4j
public class InterceptorConfig implements WebMvcConfigurer {

    @Resource
    private LoginTokenInterceptor loginTokenInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(loginTokenInterceptor)
                .addPathPatterns("/**")  // 其他接口需要token验证
                //排除knife4j的接口文档页面
                .excludePathPatterns(
                        "/doc.html",
                        "/webjars/**",
                        "/v2/api-docs",
                        "/swagger-resources/**",
                        "/configuration/ui",
                        "/configuration/security")
                //排除登录注册页面
                .excludePathPatterns("/login","/register");

    }

}