SpringBoot整合Knife4j

1.前言☕

大家好，我是Leo哥🫣🫣🫣，今天给大家带来关于精品SpringBoot专栏，暂且就给他起名为循序渐进学SpringBoot，这里我参考了我上一个专栏：循序渐进学SpringSecurity6。有需要的朋友可以抓紧学习来哈，带你从SpringSecurity从零到实战项目。好了，我们进入正题，为什么会有SpringBoot这个专栏呢，是这样的，今年Leo哥也是正在重塑知识体系，从基础到框架，而SpringBoot又是我们框架中的核心，我觉得很有必要通过以博客的形式将我的知识系列进行输出，同时也锻炼一下自己的写作能力，如果能帮到大家那就更好啦!!!本地系列教程会从SpringBoot基础讲起，会以知识点+实例+项目的学习模式由浅入深对Spring Boot框架进行学习&使用。好了，话不多说让我们开始吧😎😎😎。

2.概述

Swagger是一款测试文档Api接口，具体用法见上一篇SpringBoot整合Swagger。而knife4j是对Swagger进一步封装，其优化了api文档的界面。官网doc.xiaominfo.com/knife4j/doc...。

官网：doc.xiaominfo.com/

Knife4j 的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目

一开始项目初衷是为了写一个增强版本的swagger的前端ui,但是随着项目的发展,面对越来越多的个性化需求,不得不编写后端Java代码以满足新的需求,在swagger-bootstrap-ui的 1.8.5~1.9.6 版本之间,采用的是后端Java代码和Ui都混合在一个Jar包里面的方式提供给开发者使用.这种方式虽说对于集成swagger来说很方便,只需要引入jar包即可,但是在微服务架构下显得有些臃肿。

因此,项目正式更名为knife4j,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.

swagger-bootstrap-ui 的所有特性都会集中在knife4j-spring-ui包中,并且后续也会满足开发者更多的个性化需求.

主要的变化是,项目的相关类包路径更换为 com.github.xiaoymin.knife4j 前缀,开发者使用增强注解时需要替换包路径

后端Java代码和ui包分离为多个模块的jar包,以面对在目前微服务架构下,更加方便的使用增强文档注解(使用SpringCloud微服务项目,只需要在网关层集成UI的jar包即可,因此分离前后端)

knife4j沿用swagger-bootstrap-ui的版本号,第1个版本从1.9.6开始,关于使用方法,请参考文档(摘自 knife4j 官方介绍)。

改良后的 Knife4j 更加小巧、轻量，并且功能更加强大。

3.整合Knife4j

Knife4j 完全遵循了 Swagger 的使用方式，所以我们可以直接进行切换。那就开始吧！

3.1 引入pom依赖

xml 复制代码

<dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-spring-boot-starter</artifactId>
                <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
                <version>3.0</version>
</dependency>

3.2 迁移的demo

为了方便，迁移我们之前swagger-ui模块写的案例。

源码：github.com/gaoziman/Le...

3.3 Knife4j配置

其实这里还是可以无缝衔接之前的swagger配置。

注意：SpringBoot版本2.6还是会有一些问题!!!

java 复制代码

package org.javatop.knife4j.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author : Leo
 * @version 1.0
 * @date 2024-03-23 21:08
 * @description : knife4j配置
 */
@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).enable(true)
                .select()
                //apis： 添加swagger接口提取范围
                .apis(RequestHandlerSelectors.basePackage("org.javatop.knife4j.controller"))
                .paths(PathSelectors.any())
                .build();

        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Leo哥SpringBoot项目教程合集")
                .description("Leo哥SpringBoot项目教程合集之knife4j学习")
                .contact(new Contact("程序员Leo", "https://gaoziman.blog.csdn.net/","m2942894660@163.com"))
                .version("v1.0")
                .build();
    }
}

4.4 启动项目测试

浏览器地址栏输入以下地址访问 API 文档：http://localhost:8008/doc.htm，即可看到以下效果。

是不是比 Swagger 简洁大方多了？如果想测试接口的话，可以直接点击接口，然后点击「测试」，点击发送就可以看到返回结果了。

我们这里进行测试查询所有用户。

可以看到，点击发送即可看到效果。

4.Knife4j特性

4.1 支持JSON折叠

Swagger 是不支持 JSON 折叠的，当返回的信息非常多的时候，界面就会显得非常的臃肿。Knife4j 则不同，可以对返回的JSON节点进行折叠。

4.2 下载文档

在我们前后端分离开发中，后端则需要将接口文档给前端，使其进行联动开发。而写接口文档则是一个麻烦事。

Knife4j 支持把 API 文档导出为离线文档（支持 markdown 格式、HTML 格式、Word 格式），对于我这种懒人简直就是福音，下面我们来看看效果。

这里下载我们最熟悉的markdown看看。

可以看到，接口地址，请求方式，请求数据类型，响应数据类型等等，都很齐全，包括我们的响应状态码。

4.3 设置全局参数

同时我们也可以设置一些全局参数，在每一个请求发送之前都会带上这个参数。

可以看到在我们的方法的请求头部带上了我们刚设置的全局参数。

比如之后我们可以把我们的token放到请求头传给后端进行验证。

4.4 更多功能

其实Leo哥这里只是介绍了几个常见的功能，当然官网还是有很多功能等着大家去探索。

doc.xiaominfo.com/docs/featur...

5.源码仓库

Github源码：github.com/gaoziman/Le...

6.文末推荐🍭

如果你是刚学完SSM框架，如果你想学系统的学习SpringBoot，如果你想使用SpringBoot去集成各种其他组件，那么我这份循序渐进学SpringBoot一定是首选，带你从零到深入学习SpringBoot。抓紧订阅起来吧。用知识点+案例+项目解读的学习模式由浅入深对Spring Boot框架进行学习&使用。