在現代軟件開發中，提供清晰全面的 API 文檔 至關重要。@ApiModel 和 @ApiModelProperty 這樣的代碼註解在此方面表現出色，通過增強模型及其屬性的元數據來豐富文檔內容。它們的主要功能是為這些元素命名和描述，使生成的 API 文檔更加明確。

@ApiModel 和 @ApiModelProperty 的實際用例

這些註解不僅僅是為了展示；它們在各種情景中都發揮着實際的作用：

• 文檔生成：通過這些註解整合模型名稱、描述和屬性詳情，可以簡化準確詳細的 API 文檔編制工作。
• 驗證：利用 @ApiModelProperty 可以定義驗證約束，如最大長度或最小值，幫助確保數據的完整性。
• 模型解讀：在生成的 API 指南中，@ApiModel 和 @ApiModelProperty 提供的信息有助於明確展示模型，包括示例和詳細描述。

註解應用指南

@ApiModel 的註解用法如下：

另一方面，@ApiModelProperty 的使用註解如下：

實踐案例

考慮在一個用户管理系統中的用户模型，需要為其 API 提供清晰的定義。通過為我們的 User 類添加 @ApiModel 註解，以及用 @ApiModelProperty 描述每個屬性，我們大大提高了文檔的清晰度，使其對開發人員和用户更易於理解。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
​
@ApiModel(value = "User", description = "用户模型")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1")
    private Long id;
    
    @ApiModelProperty(value = "用户名", example = "john.doe")
    private String username;
    
    @ApiModelProperty(value = "年齡", example = "25")
    private Integer age;
    
    // 省略其他屬性的getters和setters
​
    public Long getId() {
        return id;
    }
​
    public void setId(Long id) {
        this.id = id;
    }
​
    public String getUsername() {
        return username;
    }
    
    public void setUsername(String username) {
        this.username = username;
    }
​
    public Integer getAge() {
        return age;
    }
​
    public void setAge(Integer age) {
        this.age = age;
    }
}

這些註解確保了 API 文檔有效地反映了模型及其屬性，展示了名稱、描述、類型和示例值。這種方法直接導致了一個界定清晰、易於使用的 API 參考資料。

關鍵注意事項

• 集成相關的 Swagger 依賴並正確配置。
• 註解必須準確定義屬性，如名稱、描述和數據類型。
• 確保使用 @ApiModelProperty 的屬性可以公開訪問，並擁有適當的 getter 和 setter 方法。

關於註解使用的常見問題解答

問1：是否可以在一個模型上使用多個 @ApiModel 註解？

答1：不可以，一個模型應該有一個 @ApiModel 註解。

問2：一個屬性上可以應用多個 @ApiModelProperty 註解嗎？

答2：雖然一個屬性可以有多個 @ApiModelProperty 註解，通常是為了提供不同的描述和設置。

與 Apifox 整合簡化 API 管理

儘管 Swagger 很有用，但它使用起來可能比較麻煩，缺乏一些協作安全功能。因此，許多人轉向使用 Apifox 的 IDEA 插件，以獲得更強的功能和方便。它允許在 IDEA 中自動同步 Swagger 註解到 Apifox，並通過多端同步方便測試和維護。

詳細使用教程 ：如何使用 Apifox 自動生成 API 接口文檔 - 一份詳細指南

知識擴展：

• Swagger 註解 @ApiResponses 和 @ApiResponse 的用法
• Swagger 註解 @ApiImplicitParams 和 @ApiImplicitParam 的用法

參考鏈接：

• Swagger 官方文檔：https://swagger.io/docs/specification/data-models/
• SpringFox 官方文檔：https://springfox.github.io/springfox/docs/current/