Swagger2常用注解（详细教程）

导入依赖

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.9.6</version>
</dependency>

一、用于controller类上

@Api	"对请求类的说明"

@Api：请求类的说明

@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户登录，订单管理等等。
	tags="说明该类的作用"
	value="该参数没什么意义，所以不需要配置"

示例

@Api(tags = "用户登录")
@RestController
public class UserLoginController {

}

@Api 其它属性配置

属性名称	备注
value	url的路径值
tags	说明该类的作用，如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径
position	如果配置多个Api 想改变显示的顺序位置
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”
protocols	协议类型，如: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true ，将在文档中隐藏不展示

二、用于方法上面（说明参数的含义）

@ApiOperation		"方法的说明"
@ApiImplicitParams	"方法的参数的说明"
@ApiImplicitParam	"用于指定单个参数的说明"

@ApiOperation：方法的说明

@ApiOperation："用在请求的方法上，说明方法的作用"
	value="说明方法的作用"
	notes="方法的备注说明"

@ApiImplicitParams：方法的说明

@ApiImplicitParams："用在请求的方法上，包含一组参数说明"

@ApiImplicitParam：方法的说明

@ApiImplicitParam："对单个参数的说明"
	name："参数名"
	value："参数的说明、描述"
	required："参数是否必须必填"
	    paramType："参数放在哪个地方"
	        · query --> 请求参数的获取：@RequestParam
	        · header --> 请求参数的获取：@RequestHeader	      
	        · path（用于restful接口）--> 请求参数的获取：@PathVariable
	        · body（请求体）-->  @RequestBody User user
	        · form（普通表单提交）	   
	    dataType：参数类型，默认String，其它值dataType="Integer"   
	    defaultValue："参数默认值"

示例

@Api(tags = "用户登录")
@Controller
public class UserLoginController {

@ApiOperation(value="用户登录",notes="用户登录")
	
@ApiImplicitParams({
	@ApiImplicitParam(name="userName",value="用户名",required=true,paramType="form"),
	@ApiImplicitParam(name="password",value="密码",required=true,paramType="form")
	})
		
@RequestMapping("/login")
public JsonResult login(@RequestParam String userName, @RequestParam String password){
		//...
	    return JsonResult.ok(object);
	}
}

三、用于方法上面（返回参数或对象的说明）

@ApiResponses	"方法返回值的说明"
@ApiResponse	"用于指定单个参数的说明"

@ApiResponses：方法的说明

@ApiResponses："方法返回对象的说明"

@ApiResponse：方法的说明

@ApiResponse："每个参数的说明"
	code："数字，例如400"
	message："返回信息，例如:请求参数格式不对"
	response："抛出异常的类"

示例

@Api(tags = "用户登录")
@Controller
public class UserLoginController {

@ApiOperation(value="用户登录",notes="用户登录")
	
@ApiImplicitParams({
	@ApiImplicitParam(name="userName",value="用户名",required=true,paramType="form"),
	@ApiImplicitParam(name="password",value="密码",required=true,paramType="form")
	})
		
@ApiResponses({
	@ApiResponse(code = 200, message = "登录成功"),
	@ApiResponse(code = 400, message = "账号或密码错误"),
	@ApiResponse(code = 404, message = "请求路径不存在")
}) 
	
@RequestMapping("/login")
public JsonResult login(@RequestParam String userName, @RequestParam String password){
		//...
	    return JsonResult.ok(object);
	}
}

四、对象类

@ApiModel	"用在JavaBean类上，说明JavaBean的用途"
@ApiModelProperty	"用在JavaBean类的属性上面，说明此属性的的含议"

@ApiModel：方法的说明

@ApiModel："用在JavaBean类上，说明JavaBean的用途"

示例

@ApiModel(description = "用户登录")
public class UserLogin implements Serializable {

	private static final long serialVersionUID = 1L;

	@ApiModelProperty(value = "用户名",required=true)	
	private String userName;

	@ApiModelProperty(value = "密码",required=true)	
	private String password;
	
	// getter/setter省略
}

@ApiModelProperty：方法的说明

@ApiModelProperty："用在JavaBean类的属性上面，说明此属性的的含议"

示例

@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{

	@ApiModelProperty(value = "是否成功",required=true)
	private boolean success=true;	
	
	@ApiModelProperty(value = "错误码")
	private Integer errCode;
	
	@ApiModelProperty(value = "提示信息")
	private String message;
	
    @ApiModelProperty(value = "数据")
	private Object data;
		
	// getter/setter省略
}