knife4j接口文档的使用

前言：

Knife4j 是 Swagger (OpenAPI) 的增强版 UI，专为 Java Spring Boot 项目设计。它比原生 Swagger UI 更美观、功能更强大（支持离线文档 、参数缓存 、调试等）。

由于你使用的是 Spring Boot 3.2.x 和 Java 17 ，你需要使用 Knife4j 4.x 版本（基于 OpenAPI 3 / SpringDoc），而不是旧版的 3.x（基于 Swagger 2）。

更多使用及详情可参考Knife4j文档链接

一.如何查看 Spring Boot版本

Spring Boot版本号可在启动日志的打印中查看或者查看pom.xml文件中如下内容

java 复制代码

<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>3.2.12</version> <!-- ✅ 稳定版，避免兼容性问题 -->
		<relativePath/>
	</parent>

启动日志截图：

二.引入knife4j

第一步：引入依赖到pom.xml文件中

yaml 复制代码

	<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
			<version>4.5.0</version> <!-- 推荐使用最新稳定版 -->
		</dependency>

第二步：修改TestController

java 复制代码

package com.example.demo.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Slf4j
@RestController
@RequestMapping("/test")
@Tag(name = "测试控制器", description = "用于测试日志和基础功能") // 👈 分组标签
public class TestController {

    @GetMapping("/test/log")
    @Operation(summary = "测试日志输出", description = "调用此接口会在后端控制台打印各级别日志") // 👈 接口说明
    public String testLog() {
        log.trace("这是 TRACE 日志");
        log.debug("这是 DEBUG 日志");
        log.info("这是 INFO 日志");
        log.warn("这是 WARN 日志");
        log.error("这是 ERROR 日志");

        return "日志已经打印，请查看 IDEA 控制台";
    }
}

第三步：修改UserController

java 复制代码

package com.example.demo.controller;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping("/users")
@Tag(name = "用户管理", description = "用户的增删改查接口") // 👈 分组标签
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/page")
    @Operation(summary = "分页查询用户", description = "根据页码和每页大小查询用户列表")
    public Map<String, Object> getPage(
            @Parameter(description = "当前页码", example = "1") 
            @RequestParam(defaultValue = "1") int pageNum,
            
            @Parameter(description = "每页数量", example = "10") 
            @RequestParam(defaultValue = "10") int pageSize) {

        IPage<User> userPage = userService.getUserPage(pageNum, pageSize);

        Map<String, Object> result = new HashMap<>();
        result.put("code", 200);
        result.put("data", userPage.getRecords());
        result.put("total", userPage.getTotal());
        
        return result;
    }
}

第四步：启动应用并访问

1.重启 Spring Boot 应用。

2.打开浏览器访问：

java 复制代码

http://localhost:8080/doc.html

如图：

点击分页接口截图：

会根据我们用knife4j写的信息而展示