swagger常用注解

@Api

Api 注解是作用在接口类上面的注解，其主要是用来给接口类定义相关说明。

@Api(value = "user-controller")
public class UserController{
    // do something...
}

@ApiOperation

作用在接口方法上的注解，给接口添加一些具体的描述信息

@ApiOperation(value = "用户登录")
public CommonResponse<User> userLogin(@RequestBody User user){
    // do something
}

@ApiImplicitParams 和 @ApiImplicitParam

@ApiImplicitParam：给一个方法入参增加说明。
@ApiImplicitParams : 用在方法上，添加一组参数说明。

@ApiImplicitParam(name = "user")
public ServerResponse<User> userLogin(User user){
    // do something...
}

@ResponseBody
@RequestMapping("/updatePassword")
@ApiOperation(value="修改用户密码", notes="根据用户id修改密码")
@ApiImplicitParams({
    @ApiImplicitParam(name ="userId"),
    @ApiImplicitParam(name ="password"),
    @ApiImplicitParam(name = "newPassword")
})
public String updatePassword(@RequestParam(value="userId") Integer userId, @RequestParam(value="password") String password, 
        @RequestParam(value="newPassword") String newPassword){
  // do something
}

@ApiParam

ApiParam 注解同样也提供了丰富的属性，来允许我们对接口中的参数添加描述信息，包括该参数的具体含义、参数是否必须传递等。

@ApiParam和@ApiImplicitParam的功能时相同的，但是@ApiImplicitParam的适用范围更广。在非JAX-RSde 场合，比如servlet提供http接口，只能使用@ApiImplicitParam进行参数说明。

@ApiParame 既可以写在接口方法的上方，也可以写在接口中参数的位置.

@ApiParam(name="user", value = "用户对象，用于用户登录检测，必传")
public User login(User user){
    // 用户登录业务逻辑
}

public User login(@ApiParam(name="user", value = "用户对象，用于用户登录检测，必传") User user){
    // 用户登录业务逻辑
}

@ApiModel 和 @ApiModelProperty

ApiModel 注解是作用在接口相关实体类上的注解，用来对该接口相关实体类添加额外的描述信息，常常和 @ApiModelProperty 注解配合使用。@ApiModelProperty给类的属性添加描述信息。

@ApiModel(value = "用户实体，存储用户相关字段")
public class User{
   @ApiModelProperty(value = "用户Id", required = true)
   private Integer id;

   @ApiModelProperty(hidden = true)
   private String phone;
}

@ApiResponses 和 @ApiResponse

ApiResponse 注解是作用在接口方法上的注解，用来对该接口方法的一个或多个返回值（类似http状态码）进行描述，一般不会单独使用，常常和 @ApiResponses 注解配合使用。

ApiResponses 注解也是作用在接口方法上的注解，作用和 @ApiResponse 注解相同，只是在当有多个 @ApiResponse 注解同时存在时才会使用该注解。

@ApiResponse(code = 666, message = "success")
public ServerResponse<User> login(User user){
    // do something...
}

@ApiResponses( value = { 
@ApiResponse(code = 666, message = "success"),
@ApiResponse(code = 600, message = "error",)})
public ServerResponse<User> login(User user){
    // do something...
} 

@ResponseHeader

作为 @ApiResponse 的属性，作为返回数据的一部分，指定返回 header 信息

@ApiResponse(code = 666, message = "success", responseHeaders = { @ResponseHeader(name = "userLoginHeader", description = "multipart/file") }),
public ServerResponse<User> login(User user){
    // do something...
}

@Authorization 和 @AuthorizationScope

swagger提供的权限控制注解，依赖于OAuth。基本不会使用，直接使用权限控制框架即可，没必要多次一举。

@SwaggerDefinition

SwaggerDefinition 注解是作用在接口类上面的注解，其主要是用来给 Swagger 生成的 UI 界面（下称 swagger-ui 界面）做一些额外的描述。包括界面访问地址、界面版本等。

@SwaggerDefinition(host = "localhost", basePath = "localhost:9001")
public class UserController{
    // do something...
}

如果接口方法或其中的参数存在额外的文档描述，则可以通过externalDocs 属性进行绑定，即为接口方法或其中的参数提供额外的文档支持。

@SwaggerDefinition(externalDocs = @ExternalDocs(url = "localhost:8000"))
public class UserController{
    // do something...
}

@ExternalDocs

定义接口中参方法或参数额外描述文档地址。

@SwaggerDefinition(externalDocs = @ExternalDocs(url = "localhost:8000"))
public class UserController{
    // do something...
}