今日话题
基于 SpringBoot 3 整合接口API文档,包含Knife4j、Apifox 等等~
作者:云层上的光
时间:2024年7月22日 14时11分14秒
主线任务
SpringBoot 3 整合接口API文档,包含Knife4j、Apifox 依旧在 demo-todo-list 中实现~
一、集成 Knife4j
1、引用 Knife4j 依赖,修改 pom.xml 文件:
如果安装报错请查看: 支线任务一,Knife4j 安装报错
代码如下:
<!-- knife4j -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>
2、修改 resources 软件包下的 application.yaml 文件:
代码如下:
# springdoc-openapi项目配置
springdoc:
swagger-ui:
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: 'default'
paths-to-match: '/**'
packages-to-scan: com.chuxin.demotodolist.controller
# knife4j的增强配置,不需要增强可以不配
knife4j:
enable: true
setting:
language: zh_cn
3、修改 controller 软件包下的 UserController 类文件
代码如下:
package com.chuxin.demotodolist.controller;
import com.chuxin.demotodolist.common.result.Result;
import com.chuxin.demotodolist.entity.User;
import com.chuxin.demotodolist.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;
@RestController
@RequestMapping("/user")
@Tag(name = "body参数")
public class UserController {
@Autowired
private UserService userService;
// 查看 (用来演示 接口文档的)
@GetMapping("/getList1")
@Operation(summary = "获取用户列表")
public Result<List<User>> getList1(@RequestParam int page, @RequestParam int pageSize) {
return userService.getList(page, pageSize);
}
}
4、重启项目,
5、浏览器访问 Swagger UI 风格,浏览器打开:http://localhost:8080/swagger-ui/index.html
6、浏览器访问 Knife4j 风格,浏览器打开:http://localhost:8080/doc.html#/home
7、修改 entity 软件包下的 User 类文件
代码如下:
package com.chuxin.demotodolist.entity;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
@Schema(description = "用户id")
private int id;
@Schema(description = "用户名称")
private String name;
@Schema(description = "用户密码")
private String password;
}
8、浏览器访问:http://localhost:8080/doc.html#/home
9、实体类字段描述有了,不过没有参数描述,接下来我们需要对参数进行设置,修改 controller 软件包的 UserController 类文件
代码如下:
package com.chuxin.demotodolist.controller;
import com.chuxin.demotodolist.common.result.Result;
import com.chuxin.demotodolist.entity.User;
import com.chuxin.demotodolist.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import java.util.List;
@RestController
@RequestMapping("/user")
@Tag(name = "body参数")
public class UserController {
@Autowired
private UserService userService;
// 查看 (用来演示 接口文档的)
@GetMapping("/getList1")
@Operation(summary = "获取用户列表")
@Parameters({
@Parameter(name = "page", description = "页数"),
@Parameter(name = "pageSize", description = "页码"),
})
public Result<List<User>> getList1(@RequestParam int page, @RequestParam int pageSize) {
return userService.getList(page, pageSize);
}
}
10、浏览器访问:http://localhost:8080/doc.html#/home
二、集成 Apifox
1、安装 Apifox IDEA 插件(Apifox Helper),进行安装
如果 Apifox 没有注册,需要先进行注册:app.apifox.com/
打开 IDEA,点击 File --> Settings --> Plugins,搜索 Apifox Helper
2、点击 API 访问令牌
打开 Apifox, 点击左侧【头像】-->【账号设置】-->【API 访问令牌】-->【新建令牌】,填写令牌名称,点击【保存并生成令牌]】,复制令牌
3、新增令牌:填写名称和有效期,然后点击保存
4、复制令牌到编辑器中 找到 Apifox Helper
在 IDEA 中,点击 File-->Settings -->Other Settings,找到 Apifox Helper
5、点击 + 号
6、点击需要添加的项目
7、找到需要上传的 controller 类文件,点击右键进行上传
8、刷新接口文档,接口上传成功~
9、设置分享之后,就可以实现在线访问了
10、打开链接:apifox.com/apidoc/shar…
支线任务
一、Knife4j 安装报错
1、安装并没有一步安装成功,显示部分架包安装失败,尝试使用强制更新快照解决
2、尝试点击下载架包
3、下载成功
二、Knife4j 常用注解
1、@Tag
menu 菜单栏名称
代码如下:
package com.chuxin.demotodolist.controller;
import io.swagger.v3.oas.annotations.tags.Tag;
@Tag(name = "body参数")
public class UserController {
}
2、@Operation
标注接口名称,给了就按照给的名称 没给的就是方法名称
代码如下:
package com.chuxin.demotodolist.controller;
import com.chuxin.demotodolist.common.result.Result;
import com.chuxin.demotodolist.entity.User;
import com.chuxin.demotodolist.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;
@Tag(name = "body参数")
public class UserController {
// 查看 (用来演示 接口文档的)
@GetMapping("/getList1")
@Operation(summary = "获取用户列表")
public Result<List<User>> getList1(@RequestParam int page, @RequestParam int pageSize) {
return userService.getList(page, pageSize);
}
}
3、@Schema
实体类字段描述
代码如下:
package com.chuxin.demotodolist.entity;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
@Schema(description = "用户id")
private int id;
@Schema(description = "用户名称")
private String name;
@Schema(description = "用户密码")
private String password;
}
4、@Parameters 和 @Parameter
请求参数描述
代码如下:
package com.chuxin.demotodolist.controller;
import com.chuxin.demotodolist.common.result.Result;
import com.chuxin.demotodolist.entity.User;
import com.chuxin.demotodolist.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import java.util.List;
@RestController
@RequestMapping("/user")
@Tag(name = "body参数")
public class UserController {
@Autowired
private UserService userService;
// 查看 (用来演示 接口文档的)
@GetMapping("/getList1")
@Operation(summary = "获取用户列表")
@Parameters({
@Parameter(name = "page", description = "页数"),
@Parameter(name = "pageSize", description = "页码"),
})
public Result<List<User>> getList1(@RequestParam int page, @RequestParam int pageSize) {
return userService.getList(page, pageSize);
}
}
TODO 后续涉及到更多 API 会持续更新
三、关于 Knife4j
1、官方对 Knife4j 介绍:doc.xiaominfo.com/
Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案
2、Knife4j 集成之后,默认浏览器打开:http://localhost:8080/doc.html#/home
3、对接口进行请求测试:
4、js 和 ts 代码示例:
四、关于 Apifox
自动生成接口文档: 不用手写,一键点击就可以自动生成文档,当有更新时,点击一下就可以自动同步接口文档;
代码零入侵: 完美解决了使用 Swagger 在我们的代码中额外增加各种注解,导致代码可读性极差、入侵了逻辑代码的问题;
团队合作更方便: 不需要导出文件,云端管理,直接分享链接给团队即可;
生成的文档好看!
1、详细的接入步骤如下:
五、集成 Apifox 详细版本
1、安装 Apifox IDEA 插件(Apifox Helper)
打开 IDEA,点击 File --> Settings --> Plugins,搜索 Apifox Helper
2、点击 “安装”进行安装
3、配置 Apifox 访问令牌 和项目 ID
如果没有注册,需要先进行注册:app.apifox.com/
打开 Apifox, 点击左侧【头像】-->【账号设置】-->【API 访问令牌】-->【新建令牌】,填写令牌名称,点击【保存并生成令牌]】,复制令牌
4、点击 API 访问令牌
5、新增令牌:填写名称和有效期,然后点击保存
6、点击 “保存”,直接生成令牌,
7、复制令牌到编辑器中 找到 Apifox Helper
在 IDEA 中,点击 File-->Settings -->Other Settings,找到 Apifox Helper
8、点击 “上传”选项 添加 API 访问令牌,
Apifox 最新版已经不需要赋值ID了,也就是步骤9和步骤10不需要操作~
9、首次测试成功之后,需要点击 应用 按钮
10、进入 Apifox ,点击要关联的项目~
11、找到项目id,进行复制
12、点击 + 号
13、点击需要添加的项目
14、找到需要上传的 controller 类文件,点击右键进行上传
15、刷新接口文档,接口上传成功~
六、插件包手动导入
拿 Apifox 举例,如果在插件市场下载失败
1、如果插件市场某些包下载不下来,可以尝试手动导入
2、插件市场搜索
不过需要翻墙才能打开~
3、切换 version,并且选择对应的下载版本
4、idea 集成插件
5、找到下载的 zip 包,然后点击 确认 按钮
6、导入成功
代码仓库
往期内容
点击链接查看:www.yuque.com/chuxin-cs/c…