Swagger 常用注解

Controller 的注解

@Api

该注解将一个 Controller（Class）标注为一个 swagger 资源（API）。

在默认情况下，Swagger-Core 只会扫描解析具有 @Api 注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets 等等）的注解。

该注解包含以下几个重要属性：

• tags：API 分组标签。具有相同标签的 API 将会被归并在一组内展示。

• value：如果 tags 没有定义，value 将作为 Api 的 tags 使用

@ApiOperation

在指定的（路由）路径上，对一个操作或 HTTP 方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的 HTTP 请求方法及路径组合构成一个唯一操作。此注解的属性有：

• value：对操作的简单说明，长度为 120 个字母，60 个汉字。

• notes：对操作的详细说明。

• httpMethod：HTTP 请求的动作名，可选值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。

• code：默认为 200，有效值必须符合标准的HTTP Status Code Definitions。

参数的注解

@ApiImplicitParams

注解 ApiImplicitParam 的容器类，以数组方式存储。

@ApiImplicitParam

对 API 的单一参数进行注解。虽然注解 @ApiParam 同 JAX-RS 参数相绑定，但这个 @ApiImplicitParam 注解可以以统一的方式定义参数列表，也是在 Servelet 及非 JAX-RS 环境下，唯一的方式参数定义方式。注意这个注解 @ApiImplicitParam 必须被包含在注解 @ApiImplicitParams 之内。可以设置以下重要参数属性：

• name：参数名称

• value：参数的简短描述

• required：是否为必传参数

• dataType：参数类型，可以为类名，也可以为基本类型（String，int、boolean 等）

• paramType：参数的传入（请求）类型，可选的值有 path, query, body, header or form。

• header --> 请求参数的获取：@RequestHeader

• query --> 请求参数的获取：@RequestParam

• path（用于 restful 接口）--> 请求参数的获取：@PathVariable

• body（不常用）

• form（不常用）

• dataType：参数类型，默认 String，其它值 dataType="Integer"

• defaultValue：参数的默认值

Model 的注解

对于 Model 的注解，Swagger 提供了两个：@ApiModel 及 @ApiModelProperty，分别用以描述 Model 及 Model 内的属性。

@ApiModel

提供对 Swagger model 额外信息的描述。在标注 @ApiOperation 注解的操作内，所有的类将自动被内省（introspected），但利用这个注解可以做一些更加详细的 model 结构说明。主要属性有：

• value：model 的别名，默认为类名

• description：model 的详细描述

@ApiModelProperty

对 model 属性的注解，主要的属性值有：

• value：属性简短描述

• example：属性的示例值

• required：是否为必须值

响应的注解

响应的注解和参数注解类似

@ApiResponses

用在请求的方法上，表示一组响应

@ApiResponse

用在 @ApiResponses 中，一般用于表达一个错误的响应信息，主要属性有：

• code：数字，例如 400

• message：信息，例如"请求参数没填好"

• response：抛出异常的类

简单的例子

控制器类上增加@Api 注解

@Api(tags = "用户相关接口", description = "提供用户相关的 Rest API")public class UserController

通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述

@ApiOperation("新增用户接口")@PostMapping("/add")public boolean addUser(@RequestBody User user) {  	return false;}

实体描述，我们可以通过@ApiModel 和 @ApiModelProperty 注解来对我们 API 中所涉及到的对象做描述

@ApiModel("用户实体")public class User {    @ApiModelProperty("用户 id")		private int id;}