Bootstrap

springboot3 集成 knife4j(接口文档)

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

在这里插入图片描述


前言

提示::大家在开发阶段,前后端对接时,一份简洁明了的接口文档,至关重要,本文讲述了在 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分组,用于组织和管理API
  group-configs:
    - group: 'default'   # API分组名称
      paths-to-match: '/**'  # 匹配所有路径
      packages-to-scan: com.demo.demo1.controller  # 扫描的包,用于自动发现API

# knife4j的增强配置,不需要增强可以不配(详细版见下小节)
knife4j:
  enable: true
  setting:
    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)如图:

在这里插入图片描述

输出里面会有无线局域网适配器 WLAN,找到这个下面的 IPv4 地址,这个即使自己电脑的 ip,前提是你连的是 wifi 哈

在这里插入图片描述

;