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

Knife4j 文档展示异常的小坑

news 2025/8/28 7:47:18

在后端开发中，我们经常用 Knife4j（swagger 的增强工具）来自动生成 API 文档，方便前后端对接。但最近有个小伙伴遇到了个奇怪的问题：两个接口 URL 明明不一样，可 Knife4j 里只显示一个，另一个 “失踪” 了。排查半天发现，居然是方法名相同惹的祸！

示例

假设我们在 Controller 里写了两个接口：

@RestController
@RequestMapping("/user")
public class UserController {// 接口1：查询用户基本信息@GetMapping("/info")public Result getUser() {return Result.success("用户信息");}// 接口2：查询用户地址列表@GetMapping("/address/list")public Result getUser() {  // 注意这里方法名也是getUserreturn Result.success("地址列表");}
}

这两个接口的 URL 分别是/user/info和/user/address/list，HTTP 方法都是 GET，但方法名都是getUser。这时打开 Knife4j 文档会发现：只显示一个接口，另一个被 “覆盖” 了。

为啥会出现这种情况？

这得从 Knife4j（底层是 Swagger）的工作原理说起。Swagger 在生成文档时，会给每个接口分配一个唯一标识operationId，默认情况下这个标识是类名 + 方法名。

上面的例子中，两个接口的类名都是UserController，方法名都是getUser，所以生成的operationId完全相同。Knife4j 看到相同的operationId，会认为是同一个接口，自然就只显示一个了。

简单说：URL 不同但方法名相同 → 生成相同的唯一标识 → 文档展示冲突。
怎么解决？让每个接口都有 “独一无二” 的标识

方法 1：改个不一样的方法名（最简单）
既然问题出在方法名相同，那就给它们起不同的名字：

// 接口1：查询用户基本信息
@GetMapping("/info")
public Result getUserInfo() {  // 方法名：getUserInforeturn Result.success("用户信息");
}// 接口2：查询用户地址列表
@GetMapping("/address/list")
public Result getUserAddress() {  // 方法名：getUserAddressreturn Result.success("地址列表");
}

这样生成的operationId就会不同，Knife4j 就能正常展示两个接口了。

方法 2：用 @Operation 注解手动指定标识（更灵活）

如果不想改方法名（比如有代码规范限制），可以用 Swagger 的@Operation注解，手动指定operationId：

import io.swagger.v3.oas.annotations.Operation;// 接口1：查询用户基本信息
@GetMapping("/info")
@Operation(operationId = "getUserInfo")  // 手动指定唯一标识
public Result getUser() {return Result.success("用户信息");
}// 接口2：查询用户地址列表
@GetMapping("/address/list")
@Operation(operationId = "getUserAddress")  // 手动指定另一个标识
public Result getUser() {return Result.success("地址列表");
}