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

今日话题

基于 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);
    }
}