Knife4j-的使用(详细教程)

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

前言

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

上篇：Swagger-的使用

一、简介

官方文档：快速开始 | Knife4j

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

三、基本使用

1. 导入相关依赖

        <!-- knife4j 接口文档 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.7</version>
        </dependency>

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", // 作者网址
                "xx@qq.com"); // 作者邮箱
        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", // 作者网址
? ? ? ? ? ? ? ? "xx@qq.com"); // 作者邮箱
? ? ? ? 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

?