在现代 Web 开发中，为后端 API 编写清晰、准确的文档至关重要。Swagger (现已更名为 OpenAPI Specification) 是一个强大的工具集，它能够帮助我们自动生成、可视化并维护 RESTful API 文档。在 Spring Boot 项目中，我们通常通过集成 SpringFox 或 SpringDoc 库，并配合使用一系列注解来为代码添加元数据，从而生成交互式的 API 文档。
本文将详细介绍几个最核心、最常用的 Swagger 注解。
1. @Api：描述 Controller
@Api 注解用于标记一个 Controller 类，为其提供一个全局性的描述。生成的 API 文档会根据这些信息对接口进行分组和说明。
作用：用在请求类上，从整体上说明该 Controller 的作用。
tags: 为该类定义一个或多个标签。这个值会显示在 Swagger UI 的分组标题上，非常直观。value: 一个简短的描述，tags属性通常更常用且效果更好。
代码示例
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理模块") // 定义该 Controller 在 Swagger UI 中的分组名称
public class UserController {
// ... Controller 方法
}2. @ApiOperation：描述 API 方法
@ApiOperation 注解用于标记 Controller 中的具体方法，详细说明该接口的用途、功能和备注。
作用：用在具体的 API 方法上，提供该接口的详细信息。
value: 对接口用途的简短概括，会显示在 Swagger UI 的接口列表中，作为标题。notes: 更详细的备注信息，可以包含实现细节、注意事项等。
代码示例
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
@ApiOperation(value = "根据ID获取用户信息", notes = "传入用户唯一ID，返回该用户的详细信息。")
@GetMapping("/{id}")
public User getUserById(@PathVariable Long id) {
// ... 业务逻辑
}3. @ApiImplicitParams 与 @ApiImplicitParam：描述方法参数
当 API 方法的参数比较复杂，或者参数没有直接体现在方法签名中时（例如从 HttpServletRequest 中获取），可以使用这两个注解进行详细的参数说明。
@ApiImplicitParams：用于包裹一个或多个@ApiImplicitParam注解，代表一组参数说明。
@ApiImplicitParam：用于定义单个请求参数的详细信息。
name: 参数的名称。value: 参数的中文描述或说明。required: 参数是否为必需，true或false。paramType: 参数的传递方式。常见值有：
header: 参数位于请求头，对应@RequestHeader。query: URL 查询参数，对应@RequestParam。path: 路径变量，对应@PathVariable。body: 请求体中的参数。dataType: 参数的数据类型，默认为String。其他类型如Integer,Long等需要明确指定。defaultValue: 参数的默认值。
代码示例
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
@ApiOperation(value = "更新用户分页列表", notes = "根据分页参数查询用户并更新")
@ApiImplicitParams({
@ApiImplicitParam(name = "page", value = "当前页码", required = true, paramType = "query", dataType = "Integer", defaultValue = "1"),
@ApiImplicitParam(name = "size", value = "每页显示数量", required = true, paramType = "query", dataType = "Integer", defaultValue = "10"),
@ApiImplicitParam(name = "Authorization", value = "认证Token", required = true, paramType = "header", dataType = "String")
})
@PostMapping("/list")
public Page<User> updateUserList(@RequestParam Integer page, @RequestParam Integer size) {
// ... 业务逻辑
}4. @ApiResponses 与 @ApiResponse：描述响应信息
这对注解用于描述一个请求可能返回的各种响应状态，包括成功和失败的情况，有助于前端开发者更好地处理 API 的返回结果。
@ApiResponses: 用于包裹一个或多个@ApiResponse注解，代表一组可能的响应。
@ApiResponse: 用于定义单个响应的具体信息。
code: HTTP 状态码，例如200(成功),400(错误请求),404(未找到)。message: 对该状态码的描述信息。response: （可选）如果返回特定的异常或DTO类，可以在此指定。
代码示例
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
@ApiOperation(value = "创建新用户")
@ApiResponses({
@ApiResponse(code = 201, message = "用户创建成功"),
@ApiResponse(code = 400, message = "请求参数错误，例如用户名已存在或格式不正确"),
@ApiResponse(code = 500, message = "服务器内部错误")
})
@PostMapping("/create")
public ResponseEntity<Void> createUser(@RequestBody User newUser) {
// ... 业务逻辑
}通过组合使用这些注解，你可以为 Spring Boot 应用构建出功能强大、信息丰富且完全自动化的 API 文档，极大地提升团队协作效率。