從多個方面詳細闡述ruoyi swagger

ruoyi swagger是一個基於Spring Boot和Swagger2的前後端分離的快速開發平台，它可以幫助開發人員快速構建後端服務API文檔，並且提供了便捷的UI界面進行API的測試和文檔查看。它的主要功能包括API文檔自動生成、API測試、參數校驗和許可權控制等。

一、API文檔自動生成

ruoyi swagger具有自動生成API文檔的功能，可以通過註解方式在代碼中進行API介面的描述，從而生成對應的API文檔。在代碼中，通過添加@Api註解和@ApiOperation註解對介面進行描述，可以指定介面的描述信息、參數信息、返回信息等。例如：

@Api(tags = "用戶管理")
@RestController
@RequestMapping("/user")
public class UserController
{
    @Autowired
    private ISysUserService userService;
 
    /**
     * 查詢用戶列表
     */
    @ApiOperation("查詢用戶列表")
    @PreAuthorize("@ss.hasPermi('system:user:list')")
    @GetMapping("/list")
    public TableDataInfo list(SysUser user)
    {
        startPage();
        List<SysUser> list = userService.selectUserList(user);
        return getDataTable(list);
    }
}

在該示例代碼中，@Api註解指定了介面所屬的模塊標籤「用戶管理」，@ApiOperation註解指定了介面的描述信息「查詢用戶列表」。

通過這種方式，可以方便地將介面信息轉為API文檔，提供給前端開發人員或其他調用方進行參考。

二、API測試

ruoyi swagger具有方便的API測試功能，可以通過UI界面進行介面測試，方便快捷。在文檔頁面中點擊「Try it out」按鈕，即可打開介面測試窗口，輸入參數並發送請求，查看介面返回結果。例如：

通過這種方式，可以方便地對介面進行測試，快速發現問題並進行調試。

三、參數校驗

ruoyi swagger還支持對介面參數進行校驗，保證參數的合法性。在代碼中，通過在介面方法上添加@Valid註解，並在參數對象中添加相關的約束註解，可以實現參數的自動校驗。例如：

public class SysUser implements Serializable
{
    @ApiModelProperty("用戶ID")
    @NotBlank(message = "用戶ID不能為空")
    private String userId;
 
    @ApiModelProperty("部門ID")
    @NotNull(message = "部門ID不能為空")
    private Long deptId;
 
    //...
}

在該示例代碼中，@NotBlank註解用於限制用戶ID不能為空，@NotNull註解用於限制部門ID不能為空。當參數校驗失敗時，將自動返回校驗失敗的結果給調用方。

四、許可權控制

ruoyi swagger還支持對API介面進行許可權控制，保證介面的安全性。在代碼中，可以通過添加許可權相關的註解進行控制，例如@PreAuthorize註解表示在介面調用前進行許可權校驗。例如：

@ApiOperation("新增保存用戶")
@PreAuthorize("@ss.hasPermi('system:user:add')")
@PostMapping
public AjaxResult add(@Validated @RequestBody SysUser user)
{
    user.setCreateBy(SecurityUtils.getUsername());
    return toAjax(userService.insertUser(user));
}

在該示例代碼中，@PreAuthorize註解用於限制只有具有「system:user:add」許可權的用戶才能訪問該介面。

五、完整代碼示例

以下是一個完整的ruoyi swagger所在的Java Controller類的示例：

@Api(tags = "用戶管理")
@RestController
@RequestMapping("/user")
public class UserController
{
    @Autowired
    private ISysUserService userService;
 
    /**
     * 查詢用戶列表
     */
    @ApiOperation("查詢用戶列表")
    @PreAuthorize("@ss.hasPermi('system:user:list')")
    @GetMapping("/list")
    public TableDataInfo list(SysUser user)
    {
        startPage();
        List<SysUser> list = userService.selectUserList(user);
        return getDataTable(list);
    }

    /**
     * 新增保存用戶
     */
    @ApiOperation("新增保存用戶")
    @PreAuthorize("@ss.hasPermi('system:user:add')")
    @PostMapping
    public AjaxResult add(@Validated @RequestBody SysUser user)
    {
        user.setCreateBy(SecurityUtils.getUsername());
        return toAjax(userService.insertUser(user));
    }

    /**
     * 查詢用戶信息
     */
    @ApiOperation("查詢用戶信息")
    @PreAuthorize("@ss.hasPermi('system:user:query')")
    @GetMapping(value = "/{userId}")
    public AjaxResult getInfo(@PathVariable("userId") String userId)
    {
        return AjaxResult.success(userService.selectUserById(userId));
    }

    /**
     * 修改保存用戶
     */
    @ApiOperation("修改保存用戶")
    @PreAuthorize("@ss.hasPermi('system:user:edit')")
    @PutMapping
    public AjaxResult edit(@Validated @RequestBody SysUser user)
    {
        user.setUpdateBy(SecurityUtils.getUsername());
        return toAjax(userService.updateUser(user));
    }

    /**
     * 刪除用戶
     */
    @ApiOperation("刪除用戶")
    @PreAuthorize("@ss.hasPermi('system:user:remove')")
    @DeleteMapping("/{userIds}")
    public AjaxResult remove(@PathVariable String[] userIds)
    {
        return toAjax(userService.deleteUserByIds(userIds));
    }
}

在該示例代碼中，通過註解方式實現了API文檔自動生成、API測試、參數校驗和許可權控制等功能。

通過ruoyi swagger，開發人員可以方便地構建後端服務API文檔，並且通過UI界面進行API測試和文檔查看，提高開發效率和介面規範性。