前端开发 Spring Boot 入门指南:SpringBoot 3 整合接口文档,包含Knife4j、Apifox~

721 阅读6分钟

今日话题

基于 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.com/apiskills/a…

五、集成 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、导入成功

代码仓库

github.com/chuxin-cs/s…

往期内容

点击链接查看:www.yuque.com/chuxin-cs/c…