Swagger常用注解

Swagger 常用注解

使用 Swagger 注解不仅能生成自动化的 API 文档，还能显著提升后端接口的可维护性与前后端对接效率。

1. 核心注解概览

注解	作用范围	核心功能
@Api	类 (Controller)	标识 API 资源分组，通常用于定义模块名称。
@ApiOperation	方法 (Controller Method)	描述具体接口的操作意图及作用。
@ApiParam	参数 (Method Parameter)	描述请求参数的含义、是否必填等。
@ApiModel	类 (POJO/DTO/VO)	描述数据模型（实体类）的用途。
@ApiModelProperty	属性 (Field)	描述模型属性的含义、示例值及约束。

---

2. 详细用法示例

📂 模块层级：@Api

用于类上，通过 tags 属性对接口进行逻辑分组。

@RestController
@RequestMapping("/admin/employee")
@Api(tags = "员工管理相关接口")
public class EmployeeController {
    // ...
}

🛠️ 接口层级：@ApiOperation & @ApiParam

用于明确每个方法的功能，并对路径变量或查询参数进行说明。

@PostMapping("/logout")
@ApiOperation(value = "员工退出登录", notes = "清除服务端 Session 并返回成功状态")
public Result<String> logout() {
    return Result.success();
}

@GetMapping("/{id}")
@ApiOperation("根据ID查询员工信息")
public Result<Employee> getById(@ApiParam(value = "员工ID", required = true) @PathVariable Long id) {
    return Result.success(employeeService.getById(id));
}

📦 数据模型层级：@ApiModel & @ApiModelProperty

用于封装数据的实体类中，方便前端查看 Request Body 或 Response 的结构。

@Data
@ApiModel(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {

    @ApiModelProperty(value = "用户名", required = true, example = "admin")
    private String username;

    @ApiModelProperty(value = "密码", required = true, example = "123456")
    private String password;
}