swagger注解

1. @Api

用于类；表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，可以使用tags替代

Controller1

	@Api(value = "demo1测试",tags = "测试Controller1")
	@RestController
	@RequestMapping("demo/one/controller")
	public class DemoOneController {
    }

Controller2

	@Api(value = "demo2测试",tags = "测试Controller2")
	@RestController
	@RequestMapping("demo/two/controller")
	public class DemoTwoController {
    }

效果

2. @ApiOperation

用于方法
value用于方法描述
notes用于提示内容

@ApiOperation(value = "接口的功能简介",notes = "提示接口使用者注意事项")

效果

3. @ApiImplicitParams 与 @ApiImplicitParam

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

3.1@ApiImplicitParam单独使用

	@ApiOperation(value = "接口的功能简介",notes = "提示接口使用者注意事项")
    @ApiImplicitParam(dataType = "string",name = "name",
            value = "姓名",required = true,paramType = "path")
    @RequestMapping(value = "/demeOne/{name}",method = RequestMethod.GET)
    public String demeOne(@PathVariable String name) {
        System.out.println(name);
        return "hello "+ name;
    }

效果

3.2 @ApiImplicitParams 与 @ApiImplicitParam 组合使用

	@ApiOperation(value = "接口的功能介绍",notes = "提示接口使用者注意事项")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "string",name = "name",
                    value = "姓名",required = true,paramType = "path"),
            @ApiImplicitParam(dataType = "string",name = "sex",
                    value = "性别",required = true,paramType = "path"),
            @ApiImplicitParam(dataType = "int",name = "age",
                    value = "年龄",required = true,paramType = "path")
    })
    @RequestMapping(value = "/demoTwo/{name}/{sex}/{age}",method = RequestMethod.POST)
    public String demoTwo(@PathVariable String name,
                          @PathVariable String sex,
                          @PathVariable String age) {
        System.out.println(name);
        System.out.println(sex);
        System.out.println(age);
        return "hello "+ name;
    }

效果

3.3 传递的是pojo类型的参数
controller

	@ApiOperation(value = "接口的功能介绍",notes = "提示接口使用者注意事项")
    @RequestMapping(value = "/demoThree",method = RequestMethod.POST)
    public String demoThree(@RequestBody User user) {
        System.out.println(user.getName());
        System.out.println(user.getSex());
        System.out.println(user.getAge());
        return "hello "+ user.getName();
    }

pojo实体类
@ApiModelProperty(hidden = true)表示不需要在swagger页面进行展示，required表示该属性为必需的属性。
节省空间没写get、set方法

@ApiModel(value = "用户实体类",description = "这是用户对象")
public class User {
    //主键
    @ApiModelProperty(hidden = true)    //不在swagger中显示
    private Integer id;
    //姓名
    @ApiModelProperty(value = "用户名",example = "帅小伙",required = true)
    private String name;
    //性别
    @ApiModelProperty(value = "性别",example = "男/女",required = true)
    private String sex;
    //年龄
    @ApiModelProperty(value = "年龄",example = "20",required = true)
    private Integer age;
}

效果

4. @ApiResponses 与 @ApiResponse

@ApiResponses：用于请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    code：数字，例如400
    message：信息，例如"请求参数没填好"
    response：抛出异常的类

	@ApiResponses({
            @ApiResponse(code=400,message="请求参数没填好"),
            @ApiResponse(code=401,message="没有访问权限"),
            @ApiResponse(code=403,message="访问被拒绝"),
            @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对"),
            @ApiResponse(code=500,message="后台代码报错")
    })

效果