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

在使用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可以包含多个ApiImplicit