问题描述
项目使用swagger进行文档信息展示,现在有一个招聘者企业用户信息校验接口,响应参数只会返回true或是false,如何在接口文档中响应参数栏目中添加对返回字段的描述信息(true:校验成功;false:校验失败)?
swagger中响应参数的描述信息都是通过实体类中@ApiModelProperty添加,但是如果返回的是一个Boolean或是其他非对象类型,是没有地方添加这个注解的.这里说一下自己总结的处理方案.
解决方案
1.直接从方法描述注解 @ApiOperation中添加响应结果描述信息,只要能让前端明白返回的字段的含义即可.
@ApiOperation("招聘者企业用户信息校验(返回参数说明:true:校验成功;false:校验失败)") @GetMapping("/checkRecruitBusinessInfo") public ResultVo<Boolean> checkRecruitBusinessInfo(@Validated BusinessInfoDto businessInfoDto) throws Exception { Boolean businessInfoRight = newStoreService.checkRecruitBusinessInfo(businessInfoDto); return ResultVoUtil.success(businessInfoRight); }
接口文档显示如下:
2.自定义返回参数对象,标注返回字段信息.
自定义添加返回参数描述对象:
@ApiModel("招聘者企业用户信息校验返回参数信息") @Data public class ReturnInfo { @ApiModelProperty(value = "招聘者企业用户信息校验:true:校验成功;false:校验失败",dataType = "Boolean",example = "false") private Boolean businessInfoRight; }
修改controller中返回对象信息:
@ApiOperation("招聘者企业用户信息校验") @GetMapping("/checkRecruitBusinessInfo") public ResultVo<ReturnInfo> checkRecruitBusinessInfo(@Validated BusinessInfoDto businessInfoDto) throws Exception { Boolean businessInfoRight = newStoreService.checkRecruitBusinessInfo(businessInfoDto); ReturnInfo returnInfo = new ReturnInfo(); returnInfo.setBusinessInfoRight(businessInfoRight); return ResultVoUtil.success(returnInfo); }
修改之后的接口文档,标注出的地方已经显示字段的描述信息:
实际开发中只要是前后端能清楚参数传递含义使用第一种方式就可以;但是对于像我这样的强迫症选手来说,不从响应参数中显示字段含义就感觉有问题,不过第二种方式确实有点多余,只是为了显示问题去创建对象确实不是很明智的方法.如果大家平常对于swagger这种场景有其他处理方式,欢迎评论区留言!
