Swagger @ApiOperation
@ApiOperation 注解并非 Spring Boot 自带的注解，而是来自 Swagger 框架，Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，而 @ApiOperation 主要用于为 API 接口的操作添加描述信息。以下为你详细介绍：
依赖引入
如果你使用的是 Maven 项目，需要在 pom.xml 中添加 Swagger 的依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
注解作用
@ApiOperation 注解通常用于控制器（Controller）的方法上，为该方法所代表的 API 操作提供详细的描述信息，这些信息会在 Swagger 生成的 API 文档中显示，方便开发人员和测试人员理解接口的用途和功能。
常用属性
value：用于简要描述 API 操作的功能，是该注解的默认属性，通常是一个简短的句子，概括接口的主要作用。notes：提供更详细的说明信息，可包含接口的使用注意事项、业务逻辑说明等内容。response：指定该 API 操作的返回类型，Swagger 会根据此类型生成返回参数的示例和描述。httpMethod：指定该 API 操作使用的 HTTP 方法，如 "GET"、"POST"、"PUT"、"DELETE" 等。
使用示例
以下是一个简单的 Spring Boot 控制器示例，展示了 @ApiOperation 注解的使用：
java
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api")
public class UserController {
@ApiOperation(value = "获取用户信息", notes = "根据用户 ID 获取用户的详细信息", httpMethod = "GET")
@GetMapping("/users/{id}")
public String getUserInfo() {
return "User information";
}
}
代码解释
- 在上述示例中，
@ApiOperation注解应用于getUserInfo方法上。 value属性设置为 "获取用户信息"，简要说明了该接口的功能。notes属性提供了更详细的说明，即根据用户 ID 获取用户的详细信息。httpMethod属性指定了该接口使用的 HTTP 方法为 GET。
查看 API 文档
在添加了 Swagger 依赖和 @ApiOperation 注解后，启动 Spring Boot 应用程序，访问 http://localhost:8080/swagger-ui.html（端口号根据实际情况修改），即可看到生成的 API 文档，其中包含了使用 @ApiOperation 注解添加的描述信息。
需要注意的是，Springfox Swagger 2 在 Spring Boot 3.x 中不再被支持，如果你使用的是 Spring Boot 3.x，可以考虑使用 Springdoc OpenAPI 来替代。