SpringBoot项目整合Knife4J

SpringBoot项目整合Knife4J

• 前言

• • 为什么要使用API文档
  • 什么是API文档

• Knife4j

• • Knife4j的进化史
  • Swagger和Knife4J的关系

• SpringBoot整合Knife4j

• • 版本适配
  • 实现步骤
  • • 1.导入依赖
    • 2.编写配置类
    • 新建一个controller进行测试
    • 启动项目
  • Knife4j增强配置
  • 常用注解
  • • 例子展示
    • • 实体类注解
      • Controller注解

• Knife4j文档导出

• • 实现步骤
  • • 1.进入Apifox选择导入项目
    • 2.选择Knife4j进行导入
    • 导入项目
    • 选择模块导入
    • 发送请求

• 结语

  😀大家好！我是向阳🌞，一个想成为优秀全栈开发工程师的有志青年！
  📔今天我们来介绍在前后端脱离开发项目中我们会使用到的一款强大的API规范文档的框架------Knife4J。

前言

为什么要使用API文档

首先我们要明白我们为什么要去使用API文档 ，在前后端脱离 开发的情况下，前端程序员无法实时的知道后端接口开发的进度，后端程序员总不能每开发完一个接口或者更新一次接口就去wx上去跟前端程序员说，嘿！哥们哥们，我新增了一个接口，这个接口是这样这样子...这样沟通的成本也太高了，而且有时候还说不明白，搞得双方都很难受😢，在这样的情况下，API文档应运而生。

什么是API文档

API 文档 是开发者了解 API 功能和如何正确使用的主要来源。它提供了详细的指导，包括请求格式、参数说明、响应结构等，API 文档的重要性在于它作为应用程序编程接口的纲要，为开发者提供了关键的信息，帮助他们正确、高效地使用和集成特定的 API。

Knife4j

官方文档：https://doc.xiaominfo.com/docs/quick-start

开源地址：https://gitee.com/xiaoym/knife4j

我们来简单介绍一下Knife4j。knife4j 是为Java MVC 框架集成Swagger 生成Api文档的增强解决方案,前身是swagger-bootstrap-ui ,取名knife4j是希望她能像一把匕首一样小巧 ,轻量 ,并且功能强悍!

knife4j的前身是swagger-bootstrap-ui ，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j。

Knife4j的进化史

Knife4j从开源至今,目前主要经历版本的变化，分别如下:

版本	说明
1.0~1.9.6	名称是叫swagger-bootstrap-ui,蓝色风格Ui
1.9.6	蓝色皮肤风格,开始更名，增加更多后端模块
2.0~2.0.5	Ui基于Vue2.0+AntdV重写,黑色风格,参考示例，底层依赖的springfox框架版本是2.9.2,仅提供Swagger2规范的适配
2.0.6~2.0.9	底层springfox框架版本升级至2.10.5,仅提供Swagger2规范的适配
3.0~3.0.3	底层依赖springfox框架版本升级至3.0.3,OpenAPI规范是v3,过度版本，建议开发者不要使用
4.0~	区分OpenAPI2和Swagger3的Maven坐标artifactId OpenAPI2规范服务端解析框架稳定在springfox2.10.5 OpenAPI3框架服务端解析跟随springdoc项目更新迭代

Swagger和Knife4J的关系

博主在刚接触Knife4j 的时候觉得这和Swagger没什么区别嘛，都是API规范文档的框架，在查阅了部分资料后，知道了他们两个直接的联系。

Knife4j是Swagger-UI的增强版，它是在Swagger-UI 的基础上进行了改进和优化 ，提供了更加完善 的交互体验和更加美观 的UI设计。同时，它也提供了更多的扩展功能，例如在线调试和多语言支持等。

其实看完Knife4j官方文档的介绍后也差不多知道Knife4j是Swagger的升级版。

名称	开发语言&框架	状态	最后版本	风格
Knife4j	Java、JavaScript、Vue	持续更新	无	黑色
swagger-bootstrap-ui	Java、JavaScript、jQuery	停更	1.9.6	蓝色

SpringBoot整合Knife4j

okk，接下来进行我们的正题，SpringBoot项目如何接入Knife4j。

版本适配

但是在这之前我们要清楚Knife4j与SpringBoot版本之间的关系。

Spring Boot版本	Knife4j Swagger2规范	Knife4j OpenAPI3规范
1.5.x~2.0.0	<Knife4j 2.0.0	>=Knife4j 4.0.0
2.0~2.2	Knife4j 2.0.0 ~ 2.0.6	>=Knife4j 4.0.0
2.2.x~2.4.0	Knife4j 2.0.6 ~ 2.0.9	>=Knife4j 4.0.0
2.4.0~2.7.x	>=Knife4j 4.0.0	>=Knife4j 4.0.0
>= 3.0	>=Knife4j 4.0.0	>=Knife4j 4.0.0

由于目前绝大部分项目使用的还是JDK8，Knife4j OpenAPI3 需要JDK版本在17 及以上，所以我们就不作介绍。我们这块介绍的是SpringBoot版本在2.4.0~2.7.x ，Knife4j版本在 >= 4.0.0，使用Knife4j要注意版本的问题。

实现步骤

1.导入依赖

自4.0版本开始，maven组件的artifactId已经发生了变化。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>{maven仓库最新版本}</version>
</dependency>

在4.0版本之前，maven坐标如下：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>{<4.0.0版本}</version>
</dependency>

2.编写配置类

给大家看一下我的项目架构，在Knife4jConfig下编写配置类。

/**
 * Knife4j配置类
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        // 网站标题
                        .title("向阳的Swagger文档")
                        // 描述 可以穿插md语法
                        .description("# 这是描述！")
                        // 服务条款
                        .termsOfServiceUrl("......")
                        // 设置作者 服务器url 邮箱
                        .contact(new Contact("向阳", "http://localhost:9999/demo", "xxx"))
                        // 许可证
                        .license("...")
                        // 许可证url
                        .licenseUrl("....")
                        // 版本
                        .version("1.0")
                        .build())
                .groupName("test测试组")
                .select()
                // 要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.shousi.knife4jdemo.controller"))
                // 要扫描的url
                .paths(PathSelectors.any())
                .build();
    }
}

新建一个controller进行测试

下面是我创建的一个测试接口，类命为TestController。

@Api(tags = "测试模块")
@RestController
@RequestMapping("/test")
public class TestController {
    @GetMapping("/world")
    public String world(){
        return "world knife4j";
    }

    @ApiOperation(value = "打招呼")
    @GetMapping("/hello")
    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    public String hello(@RequestParam("name") String name){
        return "hello" + name;
    }
}

启动项目

启动项目，访问http://localhost:端口号/doc.html 。即可进入API文档。

Knife4j增强配置

在yml配置文件中添加增强配置 ，在第一次进入API管理文档时需要填写账号、密码，防止网址泄露让外来人员进行破坏。

knife4j:
  enable: true
  # 开启Swagger的Basic认证功能,默认是false
  basic:
    enable: true
    # 用户名
    username: root
    # 密码
    password: 123456

同样可以设置production 为false ，在生产环境下不开放Knife4j。

knife4j:
  production: false

常用注解

注解	解释	相关参数
@Api	对某个Controller进行详细描述	tags：该controller的名称
@ApiOperation	对某个接口/方法进行详细描述	value：该接口的详细名称/功能
@ApiImplicitParam	对某个接口/方法的单个参数进行详细描述	name：参数的名称 value：参数的描述 required：是否必填 dataType：参数类型
@ApiImplicitParams	对某个接口/方法的多个参数进行详细描述	name：参数的名称 value：参数的描述 required：是否必填 dataType：参数类型
@ApiModel	对某个实体类的基本信息进行描述	description：实体类的描述
@ApiModelProperty	对某个实体类的每个属性的进行详细描述	name：参数的名称 value：参数的描述 required：是否必填 dataType：参数类型

例子展示

实体类注解

当然也可以对实体类进行更详细的配置，例如设置dataType 属性类型、required 是否必须填写。

Controller注解

Knife4j文档导出

相信大家应该都使用过Apifox 这款API文档（如果没有使用过可以在评论区留言，下一期可以详细介绍一下），可以将项目的Knife4j文档 导入Apifox 当中，我们不再用去一步一步手搓文档。

实现步骤

1.进入Apifox选择导入项目

2.选择Knife4j进行导入

注意！如果你添加了增强配置 ，需要填写yml配置文件 中对应的账户和密码，填写完毕后进行提交 。

导入项目

如果没有项目目录进行新建，如果有的话则选择已有的目录。

选择模块导入

如果是第一次导入的话，建议全部导入，如果需要筛选则自行选择。

发送请求

发送请求后，我们发现可以正常使用，这样就大功告成啦。

结语

正确的使用Knife4j 可以大大节省时间、开发成本，学会使用Knife4j还是十分重要的！有关于Knife4j的后续以及一些高级用法也会继续更新，希望大家可以多多关注。

------👦[作者]：向阳256
------⏳[更新]：2024.10.19
------🥰本人技术有限，如果有不对指正需要更改或者有更好的方法，欢迎到评论区留言。