APIModel注解的作用

一、APIModel的作用

APIModel是Swagger提供的一种注解，它可以将Swagger文档中的Model分组，将具有相同注解的Model放在一组中。

例如常见的User、Order、Product等实体类，它们可以通过APIModel注解分别放在User、Order、Product等分组中，更加清晰地展示文档的结构。

一个最简单的APIModel注解的例子：

import io.swagger.annotations.ApiModel;

@ApiModel("用户实体类")
public class User {
  private Long id;
  private String username;
  private Integer age;
  // getter/setter方法省略
}

在上面的例子中，我们在User类上添加了一个@ApiModel注解，并在注解中指定了该Model的名称为“用户实体类”。这样，在生成Swagger文档时，就会将所有带有同一个名称的Model放在一组中。

二、APIModelProperty的作用

APIModelProperty注解是Swagger提供的另外一个注解，它用于描述Model中的属性的信息。通过使用APIModelProperty，我们可以为Model中的每一个属性添加注释、设定默认值、判断必填等关键信息。

下面是一个完整的使用APIModelProperty注解的例子：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {
  @ApiModelProperty("用户ID")
  private Long id;

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

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

  // getter/setter方法省略
}

在上面的例子中，我们可以看到每一个属性都有对应的ApiModelProperty注解。注解中的value属性用于描述属性的名称，example属性用于设定属性的默认值，required属性用于判断当前属性是否是必填项。

三、APIModel和APIModelProperty的混合使用

通过混合使用APIModel和APIModelProperty注解，我们可以非常清晰地展示一个Model的整个结构。

下面是一个完整的使用APIModel和APIModelProperty注解的例子：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {
  @ApiModelProperty("用户ID")
  private Long id;

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

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

  @ApiModelProperty(value = "用户所在城市")
  private String city;

  @ApiModelProperty(value = "用户邮箱", example = "xxx@xx.com")
  private String email;

  // getter/setter方法省略
}

在上面的例子中，我们可以清晰地看到User这个Model一共有五个属性，每一个属性都有对应的ApiModelProperty注解，并且都被包含在一个名为“用户实体类”的APIModel分组中。这样，当我们使用Swagger展示这个API的文档时，就能快速了解到User这个实体类的完整结构。

四、APIModel和APIModelProperty的细节注意事项

1. 为了更好地展示Model的结构，我们可以在相似的Model中共用一个APIModel注解。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {
  // 省略属性及注解
}

@ApiModel("订单实体类")
public class Order {
  // 省略属性及注解
}

@ApiModel("商品实体类")
public class Product {
  // 省略属性及注解
}

2. 为了更好地展示ModelProperty属性的含义，我们可以在属性上添加的注解尽量完整。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {
  @ApiModelProperty(value = "用户ID", example = "1")
  private Long id;

  @ApiModelProperty(value = "用户名", example = "张三", required = true, notes = "用户名不能为中文")
  private String username;

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

3. 为了更方便地管理ApiModelProperty属性，我们可以将一些常用的属性放在统一的位置进行管理。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {
  @ApiModelProperty("用户ID")
  private Long id;

  @ApiModelProperty(value = "用户名", example = "张三")
  private String username;

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

  public String getEmail() {
    return email;
  }

  public void setEmail(String email) {
    this.email = email;
  }

  public String getCity() {
    return city;
  }

  public void setCity(String city) {
    this.city = city;
  }

  @ApiModelProperty(hidden = true)
  private String city;

  @ApiModelProperty(value = "用户邮箱", example = "xxx@xx.com")
  private String email;
  
  // getter/setter方法省略
}

在上面的例子中，我们将所有和实体属性无关的常用属性设置在最后，并使用ApiModelProperty的hidden属性将其隐藏，以便更好地管理ApiModelProperty相关信息。

总结

通过本文的介绍，我们了解到了APIModel和APIModelProperty注解的作用和用法。通过使用这两种注解，我们可以更好地管理文档中的实体类，更加清晰地展示实体类的结构，从而提高文档的可读性和可管理性。在实际项目中，我们可以根据自己的需求灵活运用这两种注解。