Swagger @ApiOperation

@ApiOperation 注解并非 Spring Boot 自带的注解，而是来自 Swagger 框架，Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，而 @ApiOperation 主要用于为 API 接口的操作添加描述信息。以下为你详细介绍：

依赖引入

如果你使用的是 Maven 项目，需要在 pom.xml 中添加 Swagger 的依赖：

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

注解作用

@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 来替代。