Knife4j 文档展示异常的小坑

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

示例

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

java 复制代码

@RestController
@RequestMapping("/user")
public class UserController {

    // 接口1：查询用户基本信息
    @GetMapping("/info")
    public Result getUser() {
        return Result.success("用户信息");
    }

    // 接口2：查询用户地址列表
    @GetMapping("/address/list")
    public Result getUser() {  // 注意这里方法名也是getUser
        return Result.success("地址列表");
    }
}

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

为啥会出现这种情况？

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

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

简单说：URL 不同但方法名相同 → 生成相同的唯一标识 → 文档展示冲突。

怎么解决？让每个接口都有 "独一无二" 的标识

方法 1：改个不一样的方法名（最简单）

既然问题出在方法名相同，那就给它们起不同的名字：

java 复制代码

// 接口1：查询用户基本信息
@GetMapping("/info")
public Result getUserInfo() {  // 方法名：getUserInfo
    return Result.success("用户信息");
}

// 接口2：查询用户地址列表
@GetMapping("/address/list")
public Result getUserAddress() {  // 方法名：getUserAddress
    return Result.success("地址列表");
}

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

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

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

java 复制代码

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("地址列表");
}

只要operationId不一样，即使方法名相同，Knife4j 也能正确识别。

总结：避免 "撞车" 的小原则

方法名尽量体现接口功能：比如查询用户信息用getUserInfo，查询地址用getUserAddress，既直观又能避免重名。

复杂场景用 @Operation 显式指定：如果业务确实需要相同方法名，记得手动设置operationId。

其实这个问题本质上是 "唯一标识冲突"，不光 Knife4j，很多 API 文档工具都可能遇到。理解了底层原理，解决起来就很简单啦！