postmapping注解_Swagger常用注解

在使用swagger时候如果掌握一些注解的使用，则在开发过程中测试的时候可以事半功倍，尤其在与前端技术进行联调，前端技术在访问swagger中的每个api时，可以很清楚的知道每个url对应的请求类型、参数类型、参数是否非必输、参数个数等等，然后根据这些参数进行前端的快速开发，当然其他技术在测试功能的时候，也可以根据参数提示进行测试，下面介绍一些在开发过程中通常用的注解。

常用注解

1、@Api

说明每个controller层控制类的作用，即每个请求类
属性：tags：描述该类的作用

2、@RestController

它是复合注解，代表的是一个控制器，由于它同时拥有@Controller和@ResponseBody的作用，所在如果要返回JSON数据，则不需要在方法上面加@ResponseBody注解，但是它不能返回jsp、html页面

3、@RequestMapping、@GetMapping、@PostMapping、@PutMapping、@DeleteMapping

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

4、@ApiOperation

作用在控制类中的每个方法上，说明该类的作用
属性：value：说明该类的作用
以上这几个注解在代码中的使用例子如下：

//说明该类的作用
@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展示结果如下：

5、@ApiParam

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

6、@PathVariable

获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数
代码示例：

 /**
     * 根据id查询学生信息
     * @param id 学生id
     * @return
     */
@ApiOperation(value = "根据id查询学生信息")
@GetMapping("/query/{id}")
private List<Student> queryById( @ApiParam(name = "id", value = "学生id", required = true) @PathVariable("id") Long id) {
        List<Student> studentList = studentService.queryById(id);
return studentList;
}
测试示例：

请求url示例：http://127.0.0.1:8080/student/query/1

7、@RequestParam

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

 /**
     * 根据id查询学生信息
     * @param id 学生id
     * @return
     */
@ApiOperation(value = "根据id查询学生信息")
@GetMapping("/query/student")
private List<Student> queryByIdStu( @ApiParam(name = "byId", value = "学生id", required = false) @RequestParam("id") Long id) {
        List<Student> studentList = studentService.queryById(id);
return studentList;
}
测试示例：

请求url示例：http://127.0.0.1:8080/student/query/student?id=1

8、 @ApiImplicitParams、@ApiImplicitParam

定义参数的注解除了@ApiParam之外，这两个注解也可以定义参数
①、@ApiImplicitParams定义一组参数
②、@ApiImplicitParam写在@ApiImplicitParams中，定义每个参数的信息，属性为：
name：参数英文名称
value：参数中文名称
paramType：调用的url 参数形式，“query”为问号"?"后面的拼接参数，“path”为绑定的参数
代码示例：

/**
     * 学生信息查询
     * @param code 学生编号
     * @param name 学会姓名
     * @return
     */
@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";
}
测试示例：