SpringBoot整合Knife4j

1,921 阅读5分钟

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/

image-20240329221203402

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依赖

<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还是会有一些问题!!!

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,即可看到以下效果。

image-20240329222608744

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

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

image-20240329222934902

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

4.Knife4j特性

4.1 支持JSON折叠

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

image-20240329224119827

4.2 下载文档

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

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

image-20240329224346240

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

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

image-20240329224429144

4.3 设置全局参数

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

image-20240329224653017

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

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

image-20240329224822039

4.4 更多功能

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

image-20240329225054354

doc.xiaominfo.com/docs/featur…

5.源码仓库

Github源码:github.com/gaoziman/Le…

6.文末推荐🍭

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