一、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）时，常用的注解主要分为两类：

1. Swagger 核心注解（用于描述 API 信息、参数、返回值等）。
2. 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;
}

如何选择？

1. 新项目：直接使用 SpringDoc OpenAPI 3（springdoc-openapi），注解更符合 OpenAPI 规范。
2. 旧项目：如果已用 springfox-swagger2，可逐步迁移到 springdoc-openapi。

注意事项

• 确保依赖正确：
  • SpringFox（Swagger2）: springfox-boot-starter（已停止维护）。
  • SpringDoc（OpenAPI 3）: springdoc-openapi-starter-webmvc-ui。
• 注解优先级：方法级别的注解会覆盖类级别的注解。