工具类：spring cloud alibaba swagger2（一）swagger2注解应用及例子

一、类上的定义说明@Api(tages={"类的作用说明"})

例子：

/**
 * @Api
 * value="不会再界面显示出来"
 * tags="说明该类的作用，可以在UI界面上看到的注解，如果tags多个值，会生成多个list"
 * @date 2018/7/4 20:17
 */
@Api(tags = {"用户操作接口"})
@Controller
@RequestMapping("/user")
public class UserController {
    
}

二、方法上的定义说明：有两种方案，分别是 ApiOperation+@ApiImplicitParams+@ApiImplicitParam 和 @ApiOperation+@ApiParam 

第一种（推荐，有利于代码阅读)：ApiOperation+@ApiImplicitParams+@ApiImplicitParam
@ApiOperation(value = "用于方法描述query",notes = "这是用来说明该方法，提示内容")
@ApiImplicitParams({
    @ApiImplicitParam(name = "data",value = "字符串数据",dataType = "String",paramType = "path",example = "白居易",required = true,defaultValue = "白居易"),
    @ApiImplicitParam(name = "i",value = "int类型",dataType = "int",paramType = "path",example = "666",required = true,defaultValue = "666")
})
@PostMapping("/query/{data}/{i}")
@ResponseBody
public ResponseCommon query(@PathVariable String data,@PathVariable int i){
    return ResponseBuilder.buildSuccessResponse(data + i);
}

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

第二种：@ApiOperation+@ApiParam

@ApiOperation(value = "用于方法描述",notes = "用于提示内容")
@GetMapping("/{data}")
@ResponseBody
public ResponseCommon string(@ApiParam(name = "data",value = "参数说明",required = true)@PathVariable String data){
    return ResponseBuilder.buildSuccessResponse(data);
}

三、实体类的定义说明@ApiModel + @ApiModelProperty

/**
 * @author simba@onlying.cn
 * @date 2018/7/4 20:18
 */
@ApiModel(value = "用户的POJO",description = "对对象的描述")
public class UserCommon {

    @ApiModelProperty(value = "用户Id",name = "userId",dataType = "int",required = true,example = "1",hidden = true)
    private int userId;
    @ApiModelProperty(value = "用户名",name = "username",dataType = "String",required = true,example = "李白")
    private String username;
    @ApiModelProperty(value = "用户年龄",name = "age",dataType = "int",required = true,example = "888")
    private int age;
    @ApiModelProperty(value = "用户密码",name = "password",dataType = "String",required = true,example = "19491001")
    private String password;

    // getter/setter方法省略
}

四、忽略一个类或者方法的swagger2定义说明：@ApiIgnore

使用该注解忽略这个API，用于类或者方法上