当前位置：首页 > news >正文

knife4j接口文档的使用

news 2026/6/17 5:58:42

前言：

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文件中如下内容

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

启动日志截图：

二.引入knife4j

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

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

第二步：修改TestController

packagecom.example.demo.controller;importio.swagger.v3.oas.annotations.Operation;importio.swagger.v3.oas.annotations.tags.Tag;importlombok.extern.slf4j.Slf4j;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RestController;@Slf4j@RestController@RequestMapping("/test")@Tag(name="测试控制器",description="用于测试日志和基础功能")// 👈 分组标签publicclassTestController{@GetMapping("/test/log")@Operation(summary="测试日志输出",description="调用此接口会在后端控制台打印各级别日志")// 👈 接口说明publicStringtestLog(){log.trace("这是 TRACE 日志");log.debug("这是 DEBUG 日志");log.info("这是 INFO 日志");log.warn("这是 WARN 日志");log.error("这是 ERROR 日志");return"日志已经打印，请查看 IDEA 控制台";}}

第三步：修改UserController

packagecom.example.demo.controller;importcom.baomidou.mybatisplus.core.metadata.IPage;importcom.example.demo.entity.User;importcom.example.demo.service.UserService;importio.swagger.v3.oas.annotations.Operation;importio.swagger.v3.oas.annotations.Parameter;importio.swagger.v3.oas.annotations.tags.Tag;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.web.bind.annotation.*;importjava.util.HashMap;importjava.util.Map;@RestController@RequestMapping("/users")@Tag(name="用户管理",description="用户的增删改查接口")// 👈 分组标签publicclassUserController{@AutowiredprivateUserServiceuserService;@GetMapping("/page")@Operation(summary="分页查询用户",description="根据页码和每页大小查询用户列表")publicMap<String,Object>getPage(@Parameter(description="当前页码",example="1")@RequestParam(defaultValue="1")intpageNum,@Parameter(description="每页数量",example="10")@RequestParam(defaultValue="10")intpageSize){IPage<User>userPage=userService.getUserPage(pageNum,pageSize);Map<String,Object>result=newHashMap<>();result.put("code",200);result.put("data",userPage.getRecords());result.put("total",userPage.getTotal());returnresult;}}