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 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已经发生了变化。
com.github.xiaoymin knife4j-openapi2-spring-boot-starter {maven仓库最新版本}在4.0版本之前，maven坐标如下：
com.github.xiaoymin knife4j-spring-boot-starter {
