Swagger2 常用注释注解使用说明【总结】

一、在swagger-ui.html页面Models模块中显示实体类信息：

//只要我们的接口中，返回值中存在实体类，他就会被扫描到 swagger中
@PostMapping（value="/user"）
public User getUser(){
	return new User();
}

二、：Swagger通过注解的方式对接口进行描述

1、@Api() 注解用在类上，说明该类的作用：

• tags：接口说明，可以在页面中显示，可以配置多个，当配置多个的时候，在页面中会显示多个接口的信息

//标记一个Controller类
@Api(tags={""})		//对Controller类的中文注释
@RestController
public class HelloController{
	
}

//标记一个实体类（待验证）
@Api(tags={""})		//对实体类的中文注释
public class User{
	private String username;
	private Stirng password;
}

2、@ApiModel() 作用在实体类上，对实体类进行说明（用于实体类中的参数接收说明）：

• value：一般用于描述model类的全路径
• description：对实体类进行说明（描述参数接收说明）

//用于对实体类的注释说明
@ApiModel(value="com.test.User",description="")
public class User{
	private String username;
	private Stirng password;
}

3、@ApiModelProperty() 用于字段，表示对model属性的说明：

• value：实体类属性描述

public class User{
	@ApiModelProperty（value="用户名"） 	//实体类属性注释
	private String username;
	@ApiModelProperty（value="密码"）	//实体类属性注释
	private Stirng password;
}

4、@ApiOperation() 用在 Controller 里的方法上，说明方法的作用：

• value：接口说明
• notes：详细描述

@RestController
public class HelloController{
	@ApiOperation（value="",notes=""）		//接口注释
	@GetMapping(value = "/hello")
	public String hello(){
		return "hello";
	}
}

5、@ApiParam() 用于Controller中方法的参数添加中文注释：

• value：参数说明
• required：是否是必要参数

@RestController
public class HelloController{
	@GetMapping(value = "/getUsername")
	public String getUsername(@ApiParam(value="此处为参数注释",required = true) User user){		//参数注释
		return user.getUsername;
	}
}

6、ApiResponse 和 ApiResponses：

• @ApiResponse 用于方法上，说明接口响应的一些信息
• @ApiResponses 组装了多个 @ApiResponse
  • code：状态码
  • message：描述信息
  • response：返回值类型

@ApiResponses({ 
	@ApiResponse(code = 200, message = "OK", response = User.class) 
})
@PostMapping("/user")
public UserDto addUser(@RequestBody User user) {
}

7、ApiImplicitParam 和 ApiImplicitParams：用于方法上，为单独的请求参数进行说明

• name：参数名，对应方法中单独的参数名称
• value：参数中文说明
• required：是否必填
• paramType：参数类型，取值为 path、query、body、header、form
• dataType：参数数据类型
• defaultValue：默认值

@ApiImplicitParams({
	@ApiImplicitParam(name = "id", value = "用户ID", dataType = "string", 
					paramType = "query", required = true, defaultValue = "1") 
})
@GetMapping("/user")
public User getUser(@RequestParam("id") String id) {
    return new User();
}