RuoYi Vue 接口注解示例

若依框架分离版，使用 Swagger 来生成接口文档，本文简单介绍下，如何编写这个接口文档。

配置文件：/ruoyi-admin/src/main/resources/application.yml

# Swagger配置
swagger:
  # 是否开启swagger
  enabled: true
  # 请求前缀
  pathMapping: /dev-api

默认情况下，已经开启了 Swagger。

示例接口文件在：/ruoyi-admin/src/main/java/com/ruoyi/web/controller/tool/TestController.java

// 接口分类（在控制器中定义）
@Api(tags = "用户信息管理")

// 接口名称（在各方法前定义）
@ApiOperation("获取用户详细")

// 单个入参定义
@ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "int", paramType = "path", dataTypeClass = Integer.class)

// 多个入参定义
@ApiImplicitParams({
    @ApiImplicitParam(name = "userId", value = "用户id", dataType = "Integer", dataTypeClass = Integer.class),
    @ApiImplicitParam(name = "username", value = "用户名称", dataType = "String", dataTypeClass = String.class),
    @ApiImplicitParam(name = "password", value = "用户密码", dataType = "String", dataTypeClass = String.class),
    @ApiImplicitParam(name = "mobile", value = "用户手机", dataType = "String", dataTypeClass = String.class)
})

// 状态码响应
@ApiResponse(code = 400, message = "查询用户失败")

之后，重新构建，在管理后台“系统工具”下“系统接口”中，即可看到。

隐藏不必要的接口参数

默认情况下，会携带很多不必要的查询参数，在方法参数前增加，@ApiIgnore 即可，之后根据需要再定义查询参数。

/**
 * 查询Banner 管理列表
 */
@ApiOperation("查询 Banner")
@ApiImplicitParams({
        @ApiImplicitParam(name = "location", value = "位置", required = false, dataType = "string", paramType = "query", dataTypeClass = String.class)
})
@PreAuthorize("@ss.hasPermi('WeChat:banner:list')")
@GetMapping("/list")
public TableDataInfo list(@ApiIgnore WechatBanner wechatBanner) {
    startPage();
    List<WechatBanner> list = wechatBannerService.selectWechatBannerList(wechatBanner);
    return getDataTable(list);
}

接口返回值定义

/**
 * 生成验证码
 */
@ApiOperation("获取验证码图片")
@ApiResponses({
        @ApiResponse(code = 200, message = "成功获取成功", response = Map.class, responseContainer = "Map",
                responseHeaders = {
                        @ResponseHeader(name = "captchaEnabled", description = "是否启用验证码", response = Boolean.class),
                        @ResponseHeader(name = "code", description = "状态码", response = Integer.class),
                        @ResponseHeader(name = "img", description = "验证码图片字符串", response = String.class),
                        @ResponseHeader(name = "uuid", description = "唯一标识符", response = String.class)
                })
})
@GetMapping("/captchaImage")
public AjaxResult getCode(HttpServletResponse response) throws IOException {
    AjaxResult ajax = AjaxResult.success();
    boolean captchaEnabled = configService.selectCaptchaEnabled();
    ajax.put("captchaEnabled", captchaEnabled);
    if (!captchaEnabled) {
        return ajax;
    }

    // 保存验证码信息
    String uuid = IdUtils.simpleUUID();
    String verifyKey = CacheConstants.CAPTCHA_CODE_KEY + uuid;

    String capStr = null, code = null;
    BufferedImage image = null;

    // 生成验证码
    String captchaType = RuoYiConfig.getCaptchaType();
    if ("math".equals(captchaType)) {
        String capText = captchaProducerMath.createText();
        capStr = capText.substring(0, capText.lastIndexOf("@"));
        code = capText.substring(capText.lastIndexOf("@") + 1);
        image = captchaProducerMath.createImage(capStr);
    } else if ("char".equals(captchaType)) {
        capStr = code = captchaProducer.createText();
        image = captchaProducer.createImage(capStr);
    }

    redisCache.setCacheObject(verifyKey, code, Constants.CAPTCHA_EXPIRATION, TimeUnit.MINUTES);
    // 转换流信息写出
    FastByteArrayOutputStream os = new FastByteArrayOutputStream();
    try {
        ImageIO.write(image, "jpg", os);
    } catch (IOException e) {
        return AjaxResult.error(e.getMessage());
    }

    ajax.put("uuid", uuid);
    ajax.put("img", Base64.encode(os.toByteArray()));
    return ajax;
}

相关文章：