Controller中使用swagger注解的正确姿势

小鱼儿 2021-09-21 22:12 368阅读 0赞

在使用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是这样对应的：

![image.png][]

从上图可以看出，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。

**参考**

1.  https://blog.csdn.net/qq\_36805343/article/details/103602455
2.  https://blog.csdn.net/qq\_36805343/article/details/103599407
3.  https://blog.csdn.net/it\_erge/article/details/91492997

[image.png]: /images/20210920/d70a94dd69f441e5b81f0ada7cabb0ee.png