`@ApiOperation` 并不是 Spring 官方提供的注解，而是 **Swagger（现更名为 **OpenAPI Specification**）** 提供的一个注解，常用于 **Springfox**（Swagger 的 Spring 集成实现）中，用来对 **Controller 中的方法**进行描述，从而生成更友好的 API 文档。 --- ### ✅ 基本作用 `@ApiOperation` 用于标注在 **Controller 的方法**上，提供该接口的说明信息，比如接口用途、返回值、是否废弃等。 --- ### 📌 常用属性 | 属性名 | 类型 | 说明 | |----------------|----------|------| | `value` | String | 接口的简要描述（必填） | | `notes` | String | 接口的详细说明（可选） | | `httpMethod` | String | 指定 HTTP 方法，如 "GET", "POST" | | `response` | Class<?> | 指定返回类型（可选） | | `hidden` | boolean | 是否隐藏该接口，默认 false | | `deprecated` | boolean | 标记接口是否已废弃 | --- ### 🧪 示例代码 ```java @RestController @RequestMapping("/user") public class UserController { @ApiOperation( value = "根据ID查询用户", notes = "返回单个用户详情，包含用户名、邮箱等信息", response = UserDTO.class ) @GetMapping("/{id}") public UserDTO getUserById(@PathVariable Long id) { // ... } } ``` --- ### 📚 注意事项 - 使用 `@ApiOperation` 需要引入 Swagger 相关依赖（如 springfox-swagger2 或 springdoc-openapi-starter-webmvc-ui）。 - Spring 3.x 以后，官方推荐使用 **Springdoc OpenAPI** 替代 Springfox，后者已停止维护。 --- ### ✅ 替代方案（Springdoc OpenAPI） 如果你使用的是 Springdoc（推荐），可以用 `@Operation` 替代： ```java @Operation(summary = "根据ID查询用户", description = "返回单个用户详情") ``` --- ### ✅ 总结一句话 > `@ApiOperation` 是 Swagger 的注解，用于给 Spring 接口写文档，**不是 Spring 官方注解**，但在 Swagger 集成中非常常见。