从多个方面详细阐述ruoyi swagger

一、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测试和文档查看，提高开发效率和接口规范性。