一、@RequestParam 和 @ApiParam的常用属性
@RequestParam 和 @ApiParam 是在 Spring MVC 控制器方法中使用的注解,它们分别服务于不同的目的:
@RequestParam
RequestParam 是 Spring MVC 中用来处理 HTTP 请求参数的注解,主要用于绑定请求中的查询参数或表单字段到控制器方法的参数。
属性名 | 详解 |
---|---|
value / name | 指定请求参数的名称。如果未指定,则默认使用参数变量名作为请求参数名 |
required | 布尔值,默认为 false。当设置为 true 时,表示该请求参数是必需的,若客户端没有提供则会抛出异常 |
defaultValue | 提供一个默认值,如果请求中没有包含该参数,则使用这个默认值 |
paramType | 参数类型(如 query、form 等),但通常可以省略,Spring Boot 能够根据上下文自动推断 |
@ApiParam
ApiParam 是 Swagger 或 OpenAPI 规范的一部分,在 Springfox 或其他实现中使用,用于增强 API 文档生成,提供更丰富的参数描述信息。
属性名 | 详解 |
---|---|
value | 对应于请求参数的说明性文字,会在生成的文档中展示。 |
name | 对应于请求参数的实际名称,与 @RequestParam 的 name 属性类似 |
example | 提供一个示例值,帮助理解参数可能的取值 |
required | 表明该参数是否在调用接口时必须提供 |
allowableValues | 可以定义允许的值范围或枚举值 |
defaultValue | 在文档中显示的默认值 |
dataType | 数据类型,例如 String, Integer 等,用于详细说明参数的数据类型 |
allowMultiple | 如果参数可以接受多个值,设为 true |
结合使用时,@RequestParam 用于实际处理和验证请求参数,而 @ApiParam 则为这些参数提供了更加详细的元数据信息,以便在自动生成的 API 文档中展示给开发者
二、实际使用场景示例
/*** 审核提交* @param type* @param applyState* @param req* @return*/@AutoLog(value = "数据审核-审核提交")@ApiOperation(value = "数据审核-审核提交",notes = "数据审核-审核提交")@PostMapping(value = "/toExamines")public Result<String> toExamines(@ApiParam(value = "查询类型:1-教师,2-学生",name = "type",required = true, example = "1")@RequestParam Integer type,@ApiParam(value = "审核状态:3_审核通过,4_审核驳回",name = "applyState",required = true, example = "")@RequestParam Integer applyState,HttpServletRequest req) {// 实际业务逻辑代码return null;}
文档示例:
调试示例: