Swagger 注解 @ApiImplicitParams 和 @ApiImplicitParam 的用法

@ApiImplicitParams 用于定义多个参数，而@ApiImplicitParam 用于定义单个参数。这两个注解的作用都是描述接口的参数信息，使 Swagger 可以正确解析接口的参数并在 Swagger UI 中生成参数文档。

ApiImplicitParams 使用场景

在以下情况下，使用@ApiImplicitParams 和@ApiImplicitParam 可以提高 API 文档的可读性：

接口包含多个参数时，使用@ApiImplicitParams 定义所有参数
单个参数需要详细描述时，使用@ApiImplicitParam
参数比较复杂，包含多层嵌套结构时，使用这两个注解可以清晰描述参数结构
接口参数需要进行验证时，可以通过注解指定参数的验证规则
接口参数包含枚举值时，可以通过注解指定参数的枚举范围

用法介绍

@ApiImplicitParams 用法

@ApiImplicitParams 用于定义多个接口参数。

@ApiImplicitParams 的常见属性：

属性	类型	默认值	说明
value	String		参数集合的说明
dataType	String		参数类型
paramType	String		参数位置,可选 path,query,body,header 或 form

其中的@ApiImplicitParam 数组包含多个参数定义，示例如下：

@ApiImplicitParams({
  @ApiImplicitParam(name="param1", value="参数1"),
  @ApiImplicitParam(name="param2", value="参数2") 
})

一个完整的@ApiImplicitParams 示例：

@ApiImplicitParams({
  @ApiImplicitParam(
    name = "username", 
    value = "用户名",
    required = true,
    dataType = "String",
    paramType = "query"
  ),
  @ApiImplicitParam(
    name = "password",
    value = "密码",
    required = true,
    dataType = "String",
    paramType = "query"
  )
})

@ApiImplicitParam 用法

@ApiImplicitParam 用于定义单个接口参数。

@ApiImplicitParam 的常见属性：

属性	类型	默认值	说明
name	String		参数名
value	String		参数说明
required	boolean	FALSE	是否必填
dataType	String		参数类型
paramType	String		参数位置,可选 path,query,body,header 或 form
defaultValue	String		默认值
allowableValues	String		参数可取值,可指定范围或枚举

一个完整的@ApiImplicitParam 示例：

@ApiImplicitParam(
  name = "username",
  value = "用户名",
  required = true,
  dataType = "String",
  paramType = "query",
  defaultValue = "guest"
)

实践案例

在 SpringBoot 中的配置如下：

@RestController
@RequestMapping("/api")
public class UserController {

  @ApiOperation("用户注册接口")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String", paramType = "form"),
      @ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "String", paramType = "form"),
      @ApiImplicitParam(name = "age", value = "年龄", required = false, dataType = "int", paramType = "form"),
  })
  @PostMapping("/user/register")
  public String register(String username, String password, Integer age) {
      // 获取参数
      // 省略参数校验

      // 注册逻辑处理

      return "success";
  }

}

在这个案例中，我给出了一个用户注册接口的代码，使用@ApiImplicitParams 注解定义了 3 个接口参数：