从零学习springboot（七）--集成在线swagger文档之常用注解

1、@Api

含义：

标识一个模块的描述，一般用于restful接口的类注解

常用属性：

1）value：用于接口模块的标题描述，似乎1.5版本后不可用

2）tags：用于接口模块的标题描述

3）description：描述接口类的详细信息，副标题，虽然起作用，但是后面可能会被废弃

4）produces：接口能够返回的资源类型，以逗号分隔，如："application/json, application/xml"

5）consumes：接口能够接受的资源类型，以逗号分隔，如："application/json, application/xml"

6）protocols：接口支持的传输协议，以逗号分隔，可能的值:http, https, ws, wss

7）hidden：在文档中是否隐藏，默认false；其实使用注解@ApiIgnore更为方便。

示例

@Api(tags="用户模块操作接口", consumes="application/json", produces="application/json", protocols="http, https, ws, wss", description="用于用户接口新增、修改、删除以及查询！")
@RestController
@RequestMapping(value="users")
public class UserController {

显示

2、ApiOperation

含义：

描述具体api操作的注解

属性：

1）value：api操作的概要

2）notes：api操作的赘述

3）tags：1.5.2版本开始的api文档版本控制的标签列表

4）response：操作的相应类型，缺省Void.class

5）responseContainer：描述相应的容器，有效值："List", "Set" 或"Map"；其他值被忽略

6）responseReference：相应引用，相应可能是本地或远程引用

7）httpMethod："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"

示例：

@ApiOperation(value="查询用户所有列表", tags="v1.0", httpMethod="GET", response=PageInfoVo.class)
    @RequestMapping(method=RequestMethod.GET)
    public club.isource.platform.vo.PageInfoVo<User> selectAll() {
        return userService.selectAll();
    }

结果

3、@ApiModel

含义：

定义接口中使用的模型数据

属性：

1）value：模型的名字

2）description：详细的描述

3）parent：是否存在父类，默认Void.class

4）subTypes：是否有继承该类型的子类

5）reference：引用的相关类

示例：

@ApiModel(value="用户实体类", description="作为系统中的用户实体，是系统的核心操作人员")
@JsonIgnoreProperties(ignoreUnknown = true)
@JsonInclude(Include.NON_EMPTY)
public class User {

结果：

4、@ApiModelProperty

含义：

描述数据模型的属性注解

属性：

1）value：模型属性的含义

2）allowableValues：允许的值，例如：range[1, 5]

3）dataType：数据类型

4）required：是否必须有值，默认false

5）example：属性值的举例

6）readOnly：只读属性

7）reference：该属性是否引用其他类

8）allowEmptyValue：是否允许空值，默认false

示例：

@ApiModelProperty(value="用户唯一标识")
private Integer userid;

结果：