Swagger2 构建 RESTful APIs的使用

@Api 的使用

Api 作用在 Controller 类上，做为 Swagger 文档资源，该注解将一个 Controller（Class）标注为一个 Swagger 资源（API）。Swagger-Core 默认只会扫描解析具有 @Api 注解的类，而会自动忽略其他类别资源。

属性配置如表所示：

@ApiOperation 的使用

ApiOperation 定义在方法上，描述方法名、方法解释、返回信息、标记等信息。

@ApiImplicitParams 和 @ApiImplicitParam 的使用

@ApiImplicitParams 用于描述方法的返回信息，和 @ApiImplicitParam 注解配合使用；@ApiImplicitParam 用来描述具体某一个参数的信息，包括参数的名称、类型、限制等信息。

@ApiParam

用在请求方法中，描述参数信息
name：参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value：参数的简要说明。
defaultValue：参数默认值
required 属性是否必填，默认为false [路径参数必须填]

@ApiResponses 和 @ApiResponse 的使用

@ApiResponses 主要封装方法的返回信息和 @ApiResponse 配置起来使用，@ApiResponse 定义返回的具体信息包括返回码、返回信息等。

@ApiModel 和 @ApiModelProperty 的使用

在实际的项目中我们常常会封装一个对象作为返回值，@ApiModel 就是负责描述对象的信息，@ApiModelProperty 负责描述对象中属性的相关内容。

参考

参考：使用 Swagger 2 构建 RESTful APIs