当前位置：首页 > news >正文

Spring学习笔记07——SpringBoot常用注解记录

news 来源：原创 2025/6/23 1:23:37

一、Lombok 注解

@Data：生成所有字段的 getter/setter、toString()、equals() 和 hashCode()。

@Getter / @Setter：单独为所有字段或指定字段生成 getter/setter。

import lombok.Data;

@Data
public class User {
    private Long id;
    private String name;
}

编译后，Lombok 会为 id 和 name 自动生成 getId()、setId()、getName()、setName() 等方法。
IDE 和编译器会“看到”这些方法，但源码中无需手动编写。

二、Swagger标记

在 Spring Boot 项目中集成 Swagger（如 Swagger2 或 OpenAPI 3）时，常用的注解主要分为两类：

Swagger 核心注解（用于描述 API 信息、参数、返回值等）。
SpringFox 或 SpringDoc 注解（根据使用的 Swagger 实现库选择）。

以下是常用的 Swagger 注解及其作用：

1. 通用 Swagger 注解（OpenAPI 规范）

适用于 SpringDoc OpenAPI 3（推荐）或 SpringFox Swagger2（旧版）。

注解	作用	示例
`@Operation`	描述单个接口（方法）的作用	`@Operation(summary = "创建用户", description = "根据 User 对象创建用户")`
`@Parameter`	描述接口的单个参数	`@Parameter(name = "id", description = "用户ID", required = true)`
`@Schema`	描述模型（DTO/Entity）的字段信息	`@Schema(description = "用户姓名", example = "张三")`
`@ApiResponse`	描述接口的响应状态码和消息	`@ApiResponse(responseCode = "200", description = "成功返回用户数据")`
`@Tag`	对接口分组（如 Controller 级别的分类）	`@Tag(name = "用户管理", description = "用户相关接口")`

2. SpringFox Swagger2 注解（旧版，逐渐淘汰）

如果使用 springfox-boot-starter（Swagger2），常用以下注解：

注解	作用	示例
`@Api`	标记 Controller 类的功能（已废弃，推荐用 `@Tag`）	`@Api(tags = "用户管理")`
`@ApiOperation`	描述接口方法（旧版，推荐用 `@Operation`）	`@ApiOperation(value = "创建用户", notes = "新增用户")`
`@ApiParam`	描述方法参数（旧版，推荐用 `@Parameter`）	`@ApiParam(value = "用户ID", required = true)`
`@ApiModel`	描述 DTO/Entity 类（旧版，推荐用 `@Schema`）	`@ApiModel(description = "用户实体")`
`@ApiModelProperty`	描述类的字段（旧版，推荐用 `@Schema`）	`@ApiModelProperty(value = "用户名", example = "张三")`

3. SpringDoc OpenAPI 3 注解（新版推荐）

如果使用 springdoc-openapi-starter-webmvc-ui（OpenAPI 3），优先使用以下注解：

注解	作用	示例
`@Hidden`	隐藏接口或字段（不展示在 Swagger UI）	`@Hidden`
`@ArraySchema`	描述数组类型的字段	`@ArraySchema(schema = @Schema(type = "integer"))`

示例代码对比

旧版（SpringFox Swagger2）

@Api(tags = "用户管理")
@RestController
public class UserController {

    @ApiOperation("根据ID查询用户")
    @GetMapping("/user/{id}")
    public User getUser(@ApiParam("用户ID") @PathVariable Long id) {
        return userService.findById(id);
    }
}

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户ID")
    private Long id;
    
    @ApiModelProperty("用户名")
    private String name;
}

新版（SpringDoc OpenAPI 3）

@Tag(name = "用户管理", description = "用户相关接口")
@RestController
public class UserController {

    @Operation(summary = "根据ID查询用户", description = "返回用户详细信息")
    @GetMapping("/user/{id}")
    public User getUser(@Parameter(description = "用户ID") @PathVariable Long id) {
        return userService.findById(id);
    }
}

public class User {
    @Schema(description = "用户ID", example = "1")
    private Long id;
    
    @Schema(description = "用户名", example = "张三")
    private String name;
}