Swagger 注解 @ApiParam 的用法

@ApiParam 注解用于给控制器类方法的参数添加元数据信息，这些信息会在 Swagger 生成的 API 文档中显示。它通常用于描述参数的含义、作用、参数类型、默认值等，方便使用者更好地理解接口参数。

@ApiParam 注解使用场景

@ApiParam 注解一般适合在以下场景中运用：

接口参数较多，需要通过注解描述每个参数的作用
参数名称无法直观表达参数的作用，需要额外描述
参数为非基本类型（如自定义对象），需要描述参数类型信息
参数有默认值，需要在文档中说明默认值
参数可选或必填，需要提示用户

@ApiParam 注解用法介绍

@ApiParam 注解的常用属性如下：

属性	类型	默认值	说明
name	String		参数名
value	String		参数的描述信息
required	boolean	FALSE	是否必填参数 true - 必填 false - 非必填
defaultValue	String		参数的默认值
allowableValues	String		参数的可选值范围,多个值用逗号分隔
access	String		参数的访问类型 access = "internal" 内部参数 access = "external" 外部参数
allowMultiple	boolean	FALSE	是否允许重复参数 true - 允许 false - 不允许
hidden	boolean	FALSE	是否隐藏参数 true - 隐藏 false - 不隐藏
example	String		举例参数值
dataType	String		参数的数据类型
paramType	String		参数类型 paramType = "query" 查询参数 paramType = "path" 路径参数 paramType = "body" 请求体参数 paramType = "header" 头部参数

实践案例

@ApiOperation("用户注册")
@PostMapping("/register")
public Resp register(
    @ApiParam(name = "username", value = "用户名", required = true)
    String username,

    @ApiParam(name = "password", value = "密码", required = true, example = "123456")
    String password,

    @ApiParam(name = "age", value = "年龄",defaultValue = "18")
    int age,

    @ApiParam(name = "hobbies", value = "爱好", allowMultiple = true)
    List<String> hobbies) {

  // 方法实现

}

如上代码，给出了不同属性的使用示例，在 Swagger 文档中会生成相应的描述信息。