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註解的作用和用法。通過使用這兩種註解，我們可以更好地管理文檔中的實體類，更加清晰地展示實體類的結構，從而提高文檔的可讀性和可管理性。在實際項目中，我們可以根據自己的需求靈活運用這兩種註解。