Knife4j-的使用(详细教程)

参考文档:Knife4j-的使用(详细教程)_knife4j使用-CSDN博客

前言

之前有写过 swagger 怎么使用的教程，但是现在很多项目用的接口文档其实是 Knife4j，Knife4j 它是对 swagger 在线接口文档的一个增强，按照官网的话说就是给 swagger 做了一个更好看皮肤的同时加了一些新的功能，本章内容我会向大家介绍在项目中如整合 knife4j 以及一些使用的细节。

上篇：Swagger-的使用

一、简介

官方文档：快速开始 | Knife4j

开源地址：knife4j: Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案

三、基本使用

1. 导入相关依赖

        
        
            com.github.xiaoymin
            knife4j-spring-boot-starter
            2.0.7
        

2.配置Swagger

@Configuration // 配置类
@EnableSwagger2WebMvc // 开启 swagger2 的自动配置
@Profile({"dev","test"})//只在开发环境和测试环境开启swagger
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("加棉")
                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                                //.any() // 扫描全部的接口，默认
                                //.none() // 全部不扫描
                                .basePackage("com.jiamian.huobanpipeibackend.controller") // 扫描指定包下的接口，最为常用
                        //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                        //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口

                )
                //过滤哪些路径(比如我要将user模块屏蔽,也就是说要过滤请求路径为/user/**的)
                .paths(PathSelectors
                                .any() // 满足条件的路径，该断言总为true
                        //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                        //.ant("/user/**") // 满足字符串表达式路径
                        //.regex("") // 符合正则的路径
                )
                .build();
    }


    
    // 基本信息设置
    private ApiInfo apiInfo() {
        Contact contact = new Contact(
                "加棉", // 作者姓名
                "https://gitee.com", // 作者网址
                "[email protected]"); // 作者邮箱
        return new ApiInfoBuilder()
                .title("鱼泡伙伴匹配系统-接口文档") // 标题
                .description("众里寻他千百度，慕然回首那人却在灯火阑珊处") // 描述
                .termsOfServiceUrl("https://www.baidu.com") // 跳转连接
                .version("1.0") // 版本
                .license("Swagger-的使用(详细教程)")
                .licenseUrl("https://blog.csdn.net/m0_59084856/article/details/135019341?spm=1001.2014.3001.5501")
                .contact(contact)
                .build();
    }

}

3.启动springboot程序，报错
Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

原因：

springboot2.6以上。Spring MVC 处理程序映射匹配请求路径的默认策略已从 AntPathMatcher 更改为PathPatternParser。

解决方案：

在application.yaml中添加以下配置信息

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

附加功能1、如何让我在测试的时候用swagger，发布的时候不用swagger

使用@Profile注解来指定在什么环境下开启swagger

附加功能2、api分组

分组，如何分组，

 .groupName("加棉")

分组，如何多个分组？，我有多个docket就可以有多个.groupName

@Configuration // 配置类
@EnableSwagger2WebMvc// 开启 swagger2 的自动配置
@Profile({"dev","test"})//只在开发环境和测试环境开启swagger
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("加棉")
                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                                //.any() // 扫描全部的接口，默认
                                //.none() // 全部不扫描
                                .basePackage("com.jiamian.huobanpipeibackend.controller") // 扫描指定包下的接口，最为常用
                        //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                        //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
 
                )
                //过滤哪些路径(比如我要将user模块屏蔽,也就是说要过滤请求路径为/user/**的)
                .paths(PathSelectors
                                .any() // 满足条件的路径，该断言总为true
                        //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                        //.ant("/user/**") // 满足字符串表达式路径
                        //.regex("") // 符合正则的路径
                )
                .build();
    }
 
 
    @Bean
    public Docket docket1(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("小刘");
    }
    @Bean
    public Docket docket2(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("小郑");
    }
 
 
    // 基本信息设置
    private ApiInfo apiInfo() {
        Contact contact = new Contact(
                "加棉", // 作者姓名
                "https://gitee.com/lin-jiayou", // 作者网址
                "[email protected]"); // 作者邮箱
        return new ApiInfoBuilder()
                .title("鱼泡伙伴匹配系统-接口文档") // 标题
                .description("众里寻他千百度，慕然回首那人却在灯火阑珊处") // 描述
                .termsOfServiceUrl("https://www.baidu.com") // 跳转连接
                .version("1.0") // 版本
                .license("Swagger-的使用(详细教程)")
                .licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535")
                .contact(contact)
                .build();
    }
 
}

配置多个组

就是有很多个docket，

效果：
访问地址:/doc.htmlip+端口+项目工程路径/doc.html