如何为DTO的Schema属性添加描述信息？

当然可以啦！你完全不用为了说明字段含义就去改identifier这个简洁的字段名，咱们有好几种实用的方法能给DTO的schema属性加上清晰的描述，我结合你的代码给你讲最常用的两种：

1. 用OpenAPI的@Schema注解（推荐） #

这是现在Java生态里做API文档最常用的方式，只要引入Swagger/OpenAPI的依赖，就能给字段加描述：

import jakarta.validation.constraints.NotBlank;
import lombok.Getter;
import lombok.Setter;
import io.swagger.v3.oas.annotations.media.Schema;

@Setter
@Getter
public class LoginUserRequestDto {
    @NotBlank
    @Schema(description = "可以是用户名、邮箱或手机号")
    private String identifier;
}

当你生成API文档的时候，这个描述会直接显示在identifier字段的旁边，客户端开发者一看就明白这个字段的取值范围，完全不用改字段名。

2. 老版本Swagger的替代方案 #

如果你项目里用的是Swagger 1.x/2.x版本，那可以用@ApiModelProperty注解，用法和上面类似：

import jakarta.validation.constraints.NotBlank;
import lombok.Getter;
import lombok.Setter;
import io.swagger.annotations.ApiModelProperty;

@Setter
@Getter
public class LoginUserRequestDto {
    @NotBlank
    @ApiModelProperty(value = "可以是用户名、邮箱或手机号")
    private String identifier;
}

这些办法都能帮你在保持字段名简洁的同时，给客户端传递准确的字段含义，再也不用纠结要起一个超长的字段名啦！

内容来源于stack exchange