swagger2 常用注解

一、@Api
@Api注解放在类上面，这里的value是没用的，tags表示该controller的介绍。

二 、@ApiOperation
@ApiOperation注解用于放在方法上面，其中value是说明该类的作用，notes一般是该方法的详细描述。

三、@RequestMapping、@GetMapping、@PostMapping、@PutMapping、@DeleteMapping
定义前端访问的url，可以写在控制类上，也可以写在控制类汇总的方法上面，常用的的写在控制类上面，一般会与它的衍生注解组合使用：
@GetMapping 查询请求
@PostMapping 添加请求
@PutMapping 修改请求
@DeleteMapping 删除请求

以上方法的使用

//说明该类的作用
@Api(tags = "学生信息")
//指明该类为控制器
@RestController
//设置请求路径url
@RequestMapping("/student")
public class StudentController {
   /**
     * 根据id查询学生信息
     * @param id 学生id
     * @return
    */
    @ApiOperation(value = "根据id查询学生信息")
    @GetMapping("/query/{id}")
    private List<Student> queryById( @ApiParam(value = "学生id", required = true) @PathVariable("id") Long id) {
        List<Student> studentList = studentService.queryById(id);
        return studentList;
    }
}

swagger-ui展示结果如下：

四、@ApiParam
该注解用在方法的参数中，属性有：
name：api参数的英文名
value：api参数的描述
required：true表示参数必输，false标识参数非必输，默认为非必输
此注解通常与@RequestParam或者@PathVariable集合使用，因为它的作用只是定义每个参数（因此可以不使用，但是为了方便测试，加上效果更好），如果要获取前端的参数还需要通过@RequestParam或者@PathVariable来获取

五、@PathVariable
获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数

六、@RequestParam
获取前端传过来的参数，可以是get、post请求，通俗的说是url中"?"后面拼接的每个参数

七、@ApiImplicitParam 与 @ApiImplicitParams
@ApiImplicitParam注解用于表明前端传入的
name参数的名字，
required是否为必需项，
以及dataType参数类型，
以及paramType传递方式（query表示使用url问号的方式传参，这种比较常用，如果使用formData的方式进行传参，那么paramType的值为 form）.
当有多个参数时，需要用@ApiImplicitParams将@ApiImplicitParam包起来

以上方法的使用

@ApiImplicitParams({
            @ApiImplicitParam(name = "code", value = "学生编号", paramType = "query", required = true),
            @ApiImplicitParam(name = "name", value = "学会姓名", paramType = "query")
    })
    @ApiOperation(value = "查询学生信息")
    @PostMapping("/query/student")
    private String queryStudent(@RequestParam String code, @RequestParam String name) {
        studentService.queryStudent(code,name);
        return "query success";
    }

swagger-ui展示结果如下：

对实体类操作的注解
一、ApiModel
 该注解用在实体类上。

value: 实体类名称
description: 实体类描述
parent: 集成的父类，默认为Void.class
subTypes: 子类，默认为{}
reference: 依赖，默认为“”

二、ApiModelProperty
 该注解用在实体类的字段中。
 
name: 属性名称
value: 属性值
notes: 属性注释
dataType: 数据类型，默认为“”
required: 是否必须，默认为false
hidden: 是否隐藏该字段，默认为false
readOnly: 是否只读，默认false
reference: 依赖，，默认“”
allowEmptyValue: 是否允许空值，默认为false
allowableValues: 允许值，默认为“”

以上注解使用方法

@ApiModel(description= "返回列表查询结果集")
public class DataGrid {

	@ApiModelProperty(value = "查询记录总数")
	private Long total = 0L;
	@ApiModelProperty(value = "当前查询到的记录列表")
	private List<?> rows = new ArrayList<>();
	private List<?> footer = new ArrayList<>();

swagger-ui展示结果如下：