@RequestParam和 @ApiParam注解使用

新工作干了一段时间了，项目上使用之前没接触过的swagger，确实要方便许多，之前在上家实习的时候，项目上没有接口文档，后端和前端之间都是简单地在微信上发个接口要什么字段，英文名，中文解释。。。效率低，麻烦还容易搞错，现在只要后端顺手打上注释，项目启动，把ip和端口告诉前端，他直接就能看到接口文档，省了后端不少心。我目前用的最多的，也是直接影响到前端查看文档的注解，就是 @RequestParam和 @ApiParam，本人刚毕业的小菜鸡，欢迎大家发表自己的看法

1. @RequestParam和@ApiParam的常用属性

@RequestParam和@ApiParam所具有的属性在名字上高度重合，但意义和默认值却不相同，以下做出对比：

@RequestParam			@ApiParam
属性名	默认值	解释	属性名	默认值	解释
value	""	入参的名称，就是前端传给后端的名字	value	""	相当于@RequestParam的name属性
name	""	对参数名的描述，就是入参的中文意思	name	""	相当于@RequestParam的value属性
required	true	给入参添加限制条件，false说明前端可传可不传，true则必传，不传报错	required	false	两者一样
defaultValue	"\n\t\t\n\t\t\n\ue000\ue001\ue002\n\t\t\t\t\n"	给入参设置默认值，即使前端没有传这个参数，后端也能获取到这个参数，参数值就是defaultValue的属性值	defaultValue	""	两者一样

2. 两者搭配使用的一些具体写法

项目组内最多的写法

public DataResult<ZonesEiaPlanPageInfoVO> detail(@RequestParam @ApiParam(name = "主键", value = "id") String id) {
    
    }

写法一

这里名称和描述的位置反了
虽然前端肯定知道要传英文参数，但如果前端直接用文档调用接口，文档把中文当参数名传递给后台，那肯定得不到正确结果，报异常：Required String parameter ‘id’ is not present
这里发现并未显式设置required属性，@RequestParam的默认值是true，而@ApiParam的默认值是false，好像是@RequestParam说了算。
考虑到注解书写的先后顺序会不会有影响，自己颠倒两个注解的前后位置，又试了试，发现结果还是一样的

也有人这样写

public DataResult<ZonesEiaPlanPageInfoVO> detail(@RequestParam @ApiParam(value = "主键") String id) {
    
    }

写法二

文档显示没问题，接口调用也没有问题，但是并没有显示设置参数名称，这就要确保前端传递参数要和方法的形参名称保持一致

还有人这样写

 public DataResult<ZonesEiaPlanPageInfoVO> detail(@RequestParam @ApiParam("id") String id) {
    
    }

写法三

这样名称和描述就都是英文了，接口调用没问题，但文档可读性大大降低

最后来说说我自己是怎么写的

非必传的参数

public DataResult<ZonesEiaPlanPageInfoVO> detail(@RequestParam(value= "id", required = false) @ApiParam("主键") String id) {
    
    }

写法四

必传的参数

public DataResult<ZonesEiaPlanPageInfoVO> detail(@RequestParam("id") @ApiParam(value = "主键", required = true) String id) {
    
    }

写法五

可以看出文档对于必传参数，做了加重和标识，所以说required属性最好带上，让前端一眼看出那些参数必须向后台传递，那些又是可有可无的参数
记住一句话：@RequestParam和@ApiParam两者，谁的required属性默认值与预想效果不一致，就需要显示声明required属性值
后来发现自己好笨啊，其实直接在@ApiParam里设置好name（字段名：英文）、value（字段描述：中文）和required三者的属性值就好了。
必传参数

public DataResult<ZonesEiaPlanPageInfoVO> detail(@RequestParam @ApiParam(name = "id", value = "主键", required = true) String id) {
    
    }

非必传参数（required属性默认就是false，可省略不写）

public DataResult<ZonesEiaPlanPageInfoVO> detail(@RequestParam @ApiParam(name = "id", value = "主键", required = false) String id) {
    
    }