公司项目考虑使用swagger的注释方式。简单看了一下,使用swagger生成文档要在方法上添加额外的注解来支持swagger文档生成。大概是这个样子
/**
* @author: qiaofan
* @date: 2019/6/4 18:07
* @version: 1.0
*/
@ApiOperation("")//一句话描述该方法
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "填写入参说明",required = false,dataType = "数据类型",paramType = "入参来源" ),
@ApiImplicitParam(name = "page",value = "填写入参说明",required = false,dataType = "数据类型",paramType = "入参来源" ),
@ApiImplicitParam(name = "pagesize",value = "填写入参说明",required = false,dataType = "数据类型",paramType = "入参来源" ),
@ApiImplicitParam(name = "id1",value = "填写入参说明",required = false,dataType = "数据类型",paramType = "入参来源" ),
@ApiImplicitParam(name = "page1",value = "填写入参说明",required = false,dataType = "数据类型",paramType = "入参来源" ),
@ApiImplicitParam(name = "pagesize1",value = "填写入参说明",required = false,dataType = "数据类型",paramType = "入参来源" )
})
@GetMapping("/query/{id}/{page}/{pagesize}")
public ResultModel test(@PathVariable int id,@PathVariable int page,@PathVariable int pagesize,
@PathVariable int id1,@PathVariable int page1,@PathVariable int pagesize1) {
System.out.println(id+","+page+","+pagesize);
User user = new User();
user.setId(3);
user.setNickName("小老弟");
return ResultModel.success("id查询成功", user);
}
虽然swagger对代码有侵入,但避免了接口修改后出现的文档不一致情况。并且swagger的注解也可以起到注释的作用,并且还是国际规范。总体来说利大于弊。
总所周知,懒惰是第一生产力,写了几个swagger注释之后发现模式大致固定,所以.....
/**s回车,根据方法参数生成带有swagger注解的注释
生成格式可以自定义修改swaggerParam的值,参见下文【手动配置、3】
1、打开 File –> Settings ->Live Templets,新建一个Templet Group ,命名为swagger。
2、在新建的swagger group 下创建Live Templet,并如图填写。添加应用范围 选java
注意:1、名称 (*+‘自定义’)、说明任意
2、模板以 * 开头的,必须是以*开头,不然在方法外是获取不到参数列表的
*
* @author: $user$
* @date: $date$ $time$
* @version: 1.0
*/
@ApiOperation("$var1$")//一句话描述该方法
$swaggerParam$
3、给代码段各项填值,点击右侧 Edit variables ,填写行数值
user,date,time这些在下拉选项里选择对应的数据就可以了
swaggerParam值是一段groovyScript代码 :就是拼接字符串
groovyScript("
def result='@ApiOperation(\"接口描述\")\\n';
def params=\"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList();
def paramStr ='';
for(i = 0; i < params.size(); i++){
paramStr+='@ApiImplicitParam(name = \"' + params[i] + '\"\,value = \"' + params[i] + '\"\,required = false\,dataType = \"数据类型\"\,paramType = \"参数来源\" )' + ((i < params.size() - 1) ? '\,\\n ' : '\\n')
};
result +='' +((params.size()>1) ? '@ApiImplicitParams({\\n '+paramStr+'})': ''+paramStr+'')+'';
return result;
",methodParameters());
idea->Live Templet 各函数作用可参阅https://www.cnblogs.com/meetrice/p/5596034.html
4、点击apply ,测试是否生效
Live Templet还有很多用法,这里只是介绍配合swagger注解使用
有什么优化调整的建议,望各位大佬指出。
另外,想问一下有什么方式可以获取方法入参类型。可以一并加到swagger注释中。