在使用swagger的时候有些注解没有正确使用会导致测试时不方便,导致测试时连数据都传入不到后端,或者swagger界面的接口显示了错误的输入组件,这些都是swagger的Comtroller注解使用的一些细节没有注意到,这篇文章主要针对这方面的注解进行总结,或许能解决使用swagger的一些小诟病。
在Controller中常用的注解有:
- @Api 用它标识的Controller称为一个模块
- tag:标识模块名称
- @ApiOperation 标识一个接口,会呈现在一个模块下
- vlue: 标识接口名称
- notes:放置接口备注
- @ApiImplicitParam 标识接口的请求参数,即Controller方法的一个入参
- name:参数名称
- value:参数值提示,会在输入文本框placeholder、字段名下方显示
- paramType*:重点!这个标识swagger接收的ajax参数应该对应到Java方法的哪里,类型如下:
- query:指明一个参数接收query param参数(?a=1&b=2类型)
- path: 指明一个参数接收路径参数
- body:指明一个参数(DTO)接收ajax的request body数据,body通常是json数据。
- header:指明一个参数从header中读取
- form: 接收普通表单,不常用
- dataType*:重点!指明这个方法入参的数据类型,为一个Java的类名,默认为String,示例:dataType="QueryCriteria"、dataType="FightDTO"
- @ApiImplicitParams 标识多个请求参数,放置的是@ApiImplicitParam数组
示例:
/**
* Description: 赛事后台-赛事安排
*
* @author: liuqichun
* @date: 2021/3/26 16:24
*/
@RequiredArgsConstructor
@RestController
@Slf4j
@Api(tags = "赛事安排")
@RequestMapping("/fight/admin/fight-user")
public class AdminCompetitionScheduleController {
private final IAdminCompetitionScheduleService adminCompetitionScheduleService;
@ApiOperation(value = "赛事安排-搜索接口", notes = " \n author: liuqichun 2021/3/28")
// ApiImplicitParams可以包含多个ApiImplicitParam
// competitionId是路径参数,paramType为path,同时方法入参应使用@PathVariable表示,否则接收不到
// criteria 和 pageVO 是查询的字段DTO类,又因为他们都是GET方法,因此paramType=query
@ApiImplicitParams({
@ApiImplicitParam(name = "competitionId", value = "赛事id", paramType = "path", dataType = "Long"),
@ApiImplicitParam(name = "criteria", value = "标准查询字段", paramType = "query", dataType = "CompetitionScheduleQueryCriteria"),
@ApiImplicitParam(name = "pageVO", value = "分页对象", paramType = "query", dataType = "PageVO")
})
@GetMapping("/{competitionId}/search")
@PreAuthorize("@smpe.check()")
public Result<Object> competitionScheduleSearch(@PathVariable @NotNull Long competitionId,
CompetitionScheduleQueryCriteria criteria,
PageVO pageVO) {
criteria.setCompetitionId(competitionId);
return Result.success(adminCompetitionScheduleService.searchCompetitionScheduleUser(criteria, pageVO));
}
}
在这里我们简单把HTTP请求方法分为两类:通过query string接收数据的方法(GET、DELETE)、
通过request body接收数据的方法(POST、PUT)。
以上示例展示query string类的注解,重点是@ApiImplicitParam
注解。
总结:
通过查询字符串(query string)接收,重点是指明@ApiImplicitParam的paramType和dataType,如果paramType为body请求接收不到数据,dataType指明为DTO类,swagger会分析DTO类然后在前端页面为DTO类的字段生成文本输入框
request body接收数据的方法示例:
@ApiOperation(value = "批量匹配场次", notes = " \n author: liuqichun 2021/3/28")
@ApiImplicitParam(name = "changeUserFightDTO", value = "配置场次数据payload", paramType = "body", dataType = "ChangeUserFightDTO")
@PutMapping
@PreAuthorize("@smpe.check()")
public Result<Object> changeUserFightBatch(@Validated @RequestBody ChangeUserFightDTO changeUserFightDTO) {
return Result.success();
}
当时请求是POST、PUT等用request body传输数据的方法,通常Controller方法使用一个DTO类接收,这个DTO类对象会作映射为body的数据(json)。
DTO对象与body是这样对应的:
从上图可以看出,request body中方置的是字符串的json,而是不是单单某个数据(它们最外层没有花括号,而这样的请求过来必然报错)。
因此在@ApiImplicitParam
中参数paramType要指定body,把整个request body映射为DTO,这样Spring MVC就自动解析并注入DTO参数了。
query string 接收数组
再查询字符串中是可以接收数组的,与request body中的数组的差别是,query string的数组是多个重复的值,如下:
// 多个重复id组成一个数组
?id=1&id=2&id=3
这种方式传递数组(也不单指数组)有个弊端——数据长度限制。
示例:
@ApiOperation(value = "批量删除/删除", notes = " \n author: liuqichun 2021/3/28")
@ApiImplicitParam(name = "ids", value = "搜索结果的id数组/列表", paramType = "query", dataType = "Long", allowMultiple = true)
@DeleteMapping
@PreAuthorize("@smpe.check()")
public Result<Object> deleteBatch(@RequestParam Long[] ids) {
if (ids == null) {
throw new BadRequestException("【传入参数未ids为null】");
}
//TODO
return Result.success();
}
这里有一个主意点,要设置allowMultiple = true
,方便swagger测试时输入参数,切勿将paramType设置为body。
参考
评论区