Swagger常用註解詳解

Swagger是一個廣泛使用的API文檔工具，它可以根據代碼自動生成API文檔，並提供互動式的API測試界面。在Swagger中，註解不僅僅只是用來生成文檔，還能夠控制API的行為，比如控制參數的校驗、控制返回數據的格式、控制API的訪問許可權等。在本文中，我們將介紹Swagger常用的註解以及它們的使用方法。

一、@Api

@Api註解用來標識一個API的基本信息，包括API的名稱、描述、作者等。這些信息將會出現在生成的文檔中。@Api註解可以在Controller類上或者方法上使用。

@Api(value = "UserController", tags = {"用戶管理"})
@RestController
@RequestMapping("/users")
public class UserController {

    @ApiOperation(value = "創建用戶", notes = "根據User對象創建用戶")
    @PostMapping("/add")
    public Result addUser(@RequestBody User user) {
        //...
    }
}

在上面的示例中，@Api註解用來標識UserController類是一個用來管理用戶的Controller，其中”用戶管理”是這個API的標籤。這個標籤會出現在生成的文檔中，方便用戶查找。

二、@ApiOperation

@ApiOperation註解用來描述一個API的具體操作，包括API的名稱、請求方式、請求路徑、請求參數、返回結果等。@ApiOperation註解只能在Controller的方法上使用。

@ApiOperation(value = "創建用戶", notes = "根據User對象創建用戶")
@PostMapping("/add")
public Result addUser(@Valid @RequestBody User user) {
    //...
}

在上面的示例中，@ApiOperation註解用來描述addUser方法的功能是創建一個用戶。其中，value屬性是API的名稱，notes屬性是API的詳細描述。@PostMapping註解用來控制請求的HTTP方法，”/add”是請求路徑。

三、@ApiParam

@ApiParam註解用來描述一個API的請求參數，包括參數名稱、類型、描述、是否必填等。@ApiParam註解只能在Controller的方法的參數上使用。

@ApiOperation(value = "創建用戶", notes = "根據User對象創建用戶")
@PostMapping("/add")
public Result addUser(@ApiParam(name = "user", value = "用戶實體", required = true) @Valid @RequestBody User user) {
    //...
}

在上面的示例中，@ApiParam註解用來描述請求參數user的具體信息。其中，name屬性是參數的名稱，value屬性是參數的描述，required屬性表示該參數是否必填。

四、@ApiResponses

@ApiResponses註解用來描述一個API的可能的返回結果，包括返回狀態碼、描述信息等。@ApiResponses註解只能在Controller的方法上使用。

@ApiOperation("查詢用戶")
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "請求成功"),
        @ApiResponse(code = 401, message = "未授權"),
        @ApiResponse(code = 403, message = "禁止訪問"),
        @ApiResponse(code = 404, message = "請求路徑不存在"),
        @ApiResponse(code = 500, message = "伺服器內部錯誤")
})
@GetMapping("/{id}")
public Result getUserById(@ApiParam(value = "用戶ID", required = true) @PathVariable Long id) {
    //...
}

在上面的示例中，@ApiResponses註解用來描述getUserById方法可能的返回結果。其中，@ApiResponse註解用來描述一個具體的返回結果，包括返回狀態碼和描述信息。

五、@ApiModelProperty

@ApiModelProperty註解用來描述一個API的返回結果，包括返回對象的名稱、類型、描述等。@ApiModelProperty註解只能在DTO類的屬性上使用。

@Data
public class UserDTO {
    @ApiModelProperty(value = "用戶ID", example = "1")
    private Long id;
    @ApiModelProperty(value = "用戶名", example = "Tom")
    private String username;
    @ApiModelProperty(value = "手機號碼", example = "13800138000")
    private String mobile;
}

在上面的示例中，@ApiModelProperty註解用來描述UserDTO類中屬性的具體信息。其中，value屬性是屬性的描述，example屬性是屬性的樣例，方便用戶理解。

六、小結

Swagger是一個非常實用的API文檔工具，在大型項目中大大簡化了API文檔的維護和管理。在使用Swagger時，合理使用註解能夠幫助我們更好地控制API的行為，生成清晰易懂的API文檔。