springboot3 集成 knife4j（接口文档）

提示：文章是集成 knife4j，而非 swagger2 或者 swagger3，效果如图

在这里插入图片描述

文章目录

前言
一、添加依赖
二、如何集成
- 1.配置文件
- 2.注解部分
- - 1.@Tag
  - 2.@Operation
  - 3.@Parameter
  - 4.@Schema
- 3.使用
总结

前言

提示：：大家在开发阶段，前后端对接时，一份简洁明了的接口文档，至关重要，本文讲述了在 springboot3 的框架下，如何快速集成 knife4j。

一、添加依赖

        <dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version></dependency>

如果项目启动成功，但是跳转接口文档页面报错，那就需要删除 jackson 的相关依赖（已经帮大家踩坑了）。

二、如何集成

1.配置文件

代码如下（示例）：

# 配置springdoc-openapi，用于文档化和访问API
springdoc:# 配置Swagger UI的访问路径和排序方式swagger-ui:path: /swagger-ui.html  # Swagger UI的访问路径tags-sorter: alpha      # 按字母顺序排序标签operations-sorter: alpha  # 按字母顺序排序操作# 配置API文档的访问路径api-docs:path: /v3/api-docs  # API文档的访问路径# 配置API分组，用于组织和管理APIgroup-configs:- group: 'default'   # API分组名称paths-to-match: '/**'  # 匹配所有路径packages-to-scan: com.demo.demo1.controller  # 扫描的包，用于自动发现API# knife4j的增强配置，不需要增强可以不配（详细版见下小节）
knife4j:enable: truesetting:language: zh_cn

需要注意 packages-to-scan 后面需要大家改成自己controller的路径哈~

2.注解部分

1.@Tag

示例如图：

在这里插入图片描述

该注解用于 controller 的类上，可以标识该类包含的大致作用。具体作用如图：

在这里插入图片描述

2.@Operation

示例如图：

在这里插入图片描述

该注解用于方法上，点击用户管理菜单会显示该类中的方法。

在这里插入图片描述

3.@Parameter

示例如图：

在这里插入图片描述

该注解用于方法参数，具体作用如图：

在这里插入图片描述

4.@Schema

示例如图：

在这里插入图片描述

该注解用于实体类以及属性，具体作用如图：

在这里插入图片描述

3.使用

页面地址是在项目地址后面追加 /doc.html，例如我本地的文档地址是 http://localhost:8080/doc.html

大家可以在自己的启动文件打印出来，方便使用

@SpringBootApplication
public class Demo1Application {public static void main(String[] args) {SpringApplication.run(Demo1Application.class, args);System.out.println("============================ 项目启动成功 ============================");System.out.println(=============== http://localhost:8080/doc.html#/home ===============");System.out.println("============================ 项目启动成功 ============================");}
}

项目启动完，点击链接地址即可直接跳转！

在这里插入图片描述
当然这个是我本地的可以这么打印，如果需要给线上的，大家把 localhost 替换成线上的服务 ip，8080 替换成线上的端口号。

如果大家想要的是 swagger 那种风格的，只需要把后缀改为 /swagger-ui/index.html，例如我的地址则是： http://localhost:8080/swagger-ui/index.html#/，跳转页面如图：

在这里插入图片描述

总结

knife4j 并非只有这几个注解，我是挑选了几个最重要的，而且也基本能满足大家日常开发需求，如果需要更详细的可以跳转 knife4j 官网。

额外说下：文章并非是 springboot 集成 swagger，而是集成了knife4j 后，knife4j 还兼容了 swagger 的风格，文章开始就说明了，作为开发我更喜欢 knife4j 这种风格，左侧的菜单能更快定位接口，整个页面结构更加清晰简洁。

如果大家是在本地进行对接，那么需要前后端在一个局域网，然后后端将自己的 ip 和端口发送给前端，前端只需要将接口地址的 localhost 或者 127.0.0.1 换成后端的 ip，即可让前端也能在自己的电脑上访问接口文档~~~再说一次，务必前后端的电脑在一个局域网下

例如：http://localhost:8080/doc.html#/home
后端的 ip 是 172.16.30.206，那么我给前端的地址就是：http://172.16.30.206:8080/doc.html#/home，端口是多少就改成啥就行。
不知道自己电脑 ip 的，win+R 组合键输入 cmd，打开终端输入：ipconfig（mac 或者 linux 的是 ifconfig）如图：

在这里插入图片描述