Swagger文檔參數注釋如何區分API新增和更新場景？
在設計restful API時，新增和更新操作對參數的要求往往不同。本文探討如何在Swagger文檔中清晰地表達這種差異。
考慮一個包含create和update方法的API控制器，以及User對象：
void create(@Validated @RequestBody User user) { ... } void update(@Validated @RequestBody User user) { ... }
假設User對象的name字段在創建時必填，但在更新時可選：
@Column(length = 30) // 如何在此處注釋來區分新增和更新場景？ private String name;
單純使用@ApiModelProperty(required = true)無法滿足需求，因為它無法區分新增和更新場景。 為了解決這個問題，我們可以結合Swagger的擴展功能和一些技巧：
方法一： 使用不同的API操作
最清晰的方法是為新增和更新操作定義不同的API端點，例如/users用于新增，/users/{id}用于更新。 這樣，Swagger文檔中每個端點的參數要求就能獨立定義，避免歧義。
方法二： 利用Knife4j的擴展功能或自定義注解
Knife4j本身并不直接支持在@ApiModelProperty中區分新增和更新場景。 但是，我們可以通過以下方式實現：
-
自定義注解: 創建一個自定義注解，例如@CreateRequired和@UpdateRequired，分別標注創建和更新場景下必填的參數。 然后，編寫一個Knife4j的擴展，在生成文檔時讀取這些自定義注解，并將其信息添加到Swagger文檔中。
-
利用Knife4j的擴展點: Knife4j提供了擴展點，允許自定義文檔生成過程。 我們可以利用這些擴展點，在生成文檔之前，根據方法名（create或update）和@ApiModelProperty等信息，動態調整參數的required屬性。
方法三： 在參數描述中明確說明
雖然不夠優雅，但在@ApiModelProperty的value字段中清晰地說明每個參數在新增和更新場景下的要求，也是一種可行的方法。 例如：
@ApiModelProperty(value = "名稱，新增時必填，更新時可選")
總結:
方法一（使用不同的API端點）是最推薦的做法，因為它簡潔明了，避免了復雜的注解和擴展。 如果出于某些原因必須使用同一個端點，則方法二（自定義注解或擴展Knife4j）是更靈活的選擇，但實現起來相對復雜。 方法三是一種權宜之計，適合簡單場景。 選擇哪種方法取決于項目的復雜性和需求。
