ApiModel 与 ApiModelProperty 注解详解

2023-11-15 14:51:26

Swagger 是一款开源的 REST API 文档生成工具，可以生成各种不同语言的 API 文档，比如 Java、PHP、Python 等。ApiModel 注解和 ApiModelProperty 注解是 Swagger 中常用的两个注解，它们可以帮助我们为 API 接口生成更详细的文档。

ApiModel 注解

ApiModel 注解用于一个类是 Swagger 的模型类。该注解可以指定类的信息、版本等信息。以下是 ApiModel 注解的常用属性：

description：类的描述信息。
value：类的名称。
subTypes：类的子类型。
discriminated：指定类的子类型字段。
reference：指定类的引用类型。

ApiModelProperty 注解

ApiModelProperty 注解用于描述类中的一个属性。该注解可以指定属性的名称、类型、描述、是否必填等信息。以下是 ApiModelProperty 注解的常用属性：

name：属性的名称。
value：属性的描述信息。
dataType：属性的类型。
required：指定属性是否必填。
allowableValues：指定属性允许的值。
example：指定属性的示例值。
access：指定属性的访问级别。
position：指定属性在文档中的位置。
hidden：指定属性是否隐藏。
readOnly：指定属性是否只读。
writeOnly：指定属性是否只写。
defaultValue：指定属性的默认值。
containerType：指定属性的容器类型。
type：指定属性的类型。
format：指定属性的格式。
example：指定属性的示例值。

使用示例

@ApiModel(description = "用户模型")
public class User {

    @ApiModelProperty(value = "用户ID", required = true, example = "1")
    private Long id;

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

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

    @ApiModelProperty(value = "年龄", example = "18")
    private Integer age;

    @ApiModelProperty(value = "性别", allowableValues = {"男", "女"})
    private String gender;
}