Spring Boot 1.5.8集成Swagger2 + YApi —— Swagger常用注解说明

前言

受新型冠状病毒的影响，在家像猪一样不是睡就是吃，闲着就学着用下Swagger和YApi，特将这几天的学习成果写成了这系列的文章，希望能对大家有所帮助。武汉加油，中国加油！

Spring Boot 1.5.8集成Swagger2 + YApi —— 集成Swagger2
Spring Boot 1.5.8集成Swagger2 + YApi —— Swagger常用注解说明
Spring Boot 1.5.8集成Swagger2 + YApi —— 部署安装mongoDB
Spring Boot 1.5.8集成Swagger2 + YApi —— 部署安装YApi（在线安装）
Spring Boot 1.5.8集成Swagger2 + YApi —— 部署安装YApi（离线安装）
Spring Boot 1.5.8集成Swagger2 + YApi —— swagger接口信息导入YApi

---

常用注解汇总：

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiIgnore：用在请求的类或者方法上，表示这个类后者方法被忽略 

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

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

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

一、@Api

用在请求的类上，表示对类的说明

常用参数

参数名	作用
tags	说明该类的作用，非空时将覆盖value的值
value	描述类的作用

其他参数

参数名	作用
description	对api资源的描述，在1.5版本后不再支持
basePath	基本路径可以不配置，在1.5版本后不再支持
position	如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持
produces	设置MIME类型列表（output），例：“application/json, application/xml”，默认为空
consumes	设置MIME类型列表（input），例：“application/json, application/xml”，默认为空
protocols	设置特定协议，例：http， https， ws， wss
authorizations	获取授权列表（安全声明），如果未设置，则返回一个空的授权值
hidden	默认为false， 配置为true 将在文档中隐藏

示例

@Controller
@RequestMapping("/apiDemo")
@Api(tags ="Api注解测试类", value="测试api注解")
public class ApiController {

    @RequestMapping(value = "/addtion", method = RequestMethod.GET)
    public Object addtion(HttpServletRequest request) {
        return null;
    }
}

二、@ApiIgnore

用在请求的类或者方法上，表示这个类或者方法被忽略，不会出现在自动生成的Api文档中

示例

@Controller
@RequestMapping("/ignore")
@Api(tags ="ApiIgnore注解测试类", value="测试api注解")
public class IgnoreController {

    @RequestMapping(value = "/addtion", method = RequestMethod.GET)
    public Object addtion(HttpServletRequest request) {
        return null;
    }

    @ApiIgnore
    @RequestMapping(value = "/deletion", method = RequestMethod.GET)
    public Object deletion(HttpServletRequest request) {
        return null;
    }

}

三、@ApiOperation

用在请求的方法上，说明方法的用途、作用

常用参数

参数名	作用
value	方法的用户、作用说明
notes	该方法的备注

其它参数

参数名	作用
tags	操作标签，非空时将覆盖value的值
response	响应类型（即返回对象）
responseContainer	声明包装的响应容器（返回对象类型）。有效值为 “List”, “Set” or “Map”
responseReference	指定对响应类型的引用。将覆盖任何指定的response（）类
httpMethod	指定HTTP方法，“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
position	如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持
nickname	第三方工具唯一标识，默认为空
produces	设置MIME类型列表（output），例：“application/json, application/xml”，默认为空
consumes	设置MIME类型列表（input），例：“application/json, application/xml”，默认为空
protocols	设置特定协议，例：http， https， ws， wss
authorizations	获取授权列表（安全声明），如果未设置，则返回一个空的授权值
hidden	默认为false， 配置为true 将在文档中隐藏
responseHeaders	响应头列表
code	响应的HTTP状态代码。默认 200
extensions	扩展属性列表数组

示例

@Controller
@RequestMapping("/operation")
@Api(tags ="@ApiOperation注解示例类")
public class OperationController {

    @RequestMapping(value = "/addtion", method = RequestMethod.GET)
    public Object addtion(HttpServletRequest request) {
        return null;
    }

    @RequestMapping(value = "/deletion", method = RequestMethod.GET)
    @ApiOperation(value = "测试ApiOperation注解",notes = "swagger注解测试")
    public Object deletion(HttpServletRequest request) {
        return null;
    }
}

四、@ApiParam

用在请求方法的参数中，用于描述参数信息

常用参数

参数名	作用
name	参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value	参数的简要说明
defaultValue	参数默认值
required	属性是否必填，默认为false [路径参数必须填]

其它参数

参数名	作用
allowableValues	限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值
access	允许从API文档中过滤参数
allowMultiple	指定参数是否可以通过具有多个事件接受多个值，默认为false
hidden	隐藏参数列表中的参数
example	单个示例
examples	参数示例。仅适用于BodyParameters

示例

@Controller
@RequestMapping("/param")
@Api(tags ="@ApiParam注解示例类")
public class ParamController {
    
    @RequestMapping(value = "/addtion", method = RequestMethod.POST)
    @ApiOperation(value = "测试ApiParam注解",notes = "swagger注解测试")
    public Object addtion(
            @ApiParam(name="account", value="账户名", defaultValue="huzhenv5", required=true) String account,
            @ApiParam(name="pwd", value="密码", defaultValue="1111", required=true) String  pwd)
    {
        return null;
    }
}

五、@ApiImplicitParam & @ApiImplicitParams

与@ApiParam注解作用相似，用于对方法的参数进行说明，作用比@ApiParam更广泛

@ApiImplicitParam和@ApiImplicitParams均可直接用在请求的方法上，表示一个或者一组参数的说明

@ApiImplicitParams注解可包含一个或多个@ApiImplicitParam注解

@ApiImplicitParam注解可传参数，参数说明如下：

常用参数

参数名	作用
name	参数名，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value	参数的汉字说明、解释
required	参数是否必须传，默认为false [路径参数必填]
paramType	参数放在哪个地方： header --> 请求参数的获取：@RequestHeader query --> 请求参数的获取：@RequestParam path（用于restful接口）–> 请求参数的获取：@PathVariable body --> 不常用 form --> 不常用
dataType	参数类型，默认String，其它值dataType=“Integer”
defaultValue	参数的默认值

其它参数

参数名	作用
allowableValues	限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值
access	允许从API文档中过滤参数
allowMultiple	指定参数是否可以通过具有多个事件接受多个值，默认为false
example	单个示例
examples	参数示例，仅适用于BodyParameters

示例

@Controller
@RequestMapping("/implicit")
@Api(tags ="@ApiImplicitParam注解示例类")
public class ImplicitController {

    // 一个参数的接口
    @RequestMapping(value = "/getDemo10", method = RequestMethod.POST)
    @ResponseBody
    @ApiOperation(value = "乘以10接口",notes = "根据传的参数，返回乘以10的数字")
    @ApiImplicitParam(name = "number", value = "被乘数", required = true, paramType = "query", dataType = "int")
    public Object getDemo10(HttpServletRequest request) {
        Map<String,Object> retMap = new HashMap<String,Object>();
        Map<String,String> paramMap = PJCommon.getRequestParamMapAndSessionInfo(request);
        try{
            int value = 10 * Integer.parseInt(paramMap.get("number").toString());
            retMap.put("result", value);
            retMap.put("state", 0);
        }catch(Exception e) {
            e.printStackTrace();
            retMap.put("state", 1);
        }
        return retMap;
    }

    // 多个参数的接口
    @RequestMapping(value = "/getDemoAdd", method = RequestMethod.POST)
    @ResponseBody
    @ApiOperation(value = "相加接口",notes = "根据传的参数，返回两个数的和")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "val1", value = "相加数1", required = true, paramType = "query", dataType = "int"),
            @ApiImplicitParam(name = "val2", value = "相加数2", required = true, paramType = "query", dataType = "int")
    })
    public Object getDemoAdd(HttpServletRequest request) {
        Map<String,Object> retMap = new HashMap<String,Object>();
        Map<String,String> paramMap = PJCommon.getRequestParamMapAndSessionInfo(request);
        try{
            int value1 = Integer.parseInt(paramMap.get("val1").toString());
            int value2 = Integer.parseInt(paramMap.get("val2").toString());
            retMap.put("result", value1 + value2);
            retMap.put("state", 0);
        }catch(Exception e) {
            e.printStackTrace();
            retMap.put("state", 1);
        }
        return retMap;
    }
}

六、@ApiResponse & @ApiResponses

@ApiResponses用在请求方法上，表示一组响应信息说明

@ApiResponses注解可以包含一个或者多个@ApiResponse注解

@ApiResponse注解直接使用在请求方法上无效

常用参数

参数名	作用
code	状态码，例如200、400
msg	状态码对应的信息，例如请求不存在
response	抛出异常的类

示例

@Controller
@RequestMapping("/response")
@Api(tags ="@ApiResponse注解示例类")
public class ResponseController {

    // 一个参数的接口
    @RequestMapping(value = "/addtion", method = RequestMethod.POST)
    @ApiResponses({
            @ApiResponse(code=400, message="请求参数没填好"),
            @ApiResponse(code=404, message="请求路径没有或页面跳转路径不对")
    })
    public Object addtion(HttpServletRequest request) {
        return null;
    }

}

七、@ApiModel & @ApiModelProperty

对请求或者响应的类进行说明，@ApiModel和@ApiModelProperty一般配置使用

注意：

1. @ApiModelProperty对类的私有属性进行注解时，如果该私有属性没有set或者get方法，则该私有属性在api文档中不会展示
2. 当注解的类作为参数时，该参数需要有@RequestBody注解，否则该该参数不会出现在api文档的参数列表中

@ApiModel 常用参数

参数名	作用
value	类的说明
description	类的描述

@ApiModel 其它参数

参数名	作用
parent	为模型提供父类以允许描述继承关系
discriminatory	支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型
subTypes	从此模型继承的子类型数组
reference	指定对应类型定义的引用，覆盖指定的任何其他元数据

@ApiModelProperty 常用参数

参数名	作用
value	属性简要说明
name	运行覆盖属性的名称。重写属性名称

@ApiModelProperty 其它参数

参数名	作用
allowableValues	限制参数可接收的值，三种方法，固定取值，固定范围
access	过滤属性，参阅:io.swagger.core.filter.SwaggerSpecFilter
notes	目前尚未使用
dataType	参数的数据类型，可以是类名或原始数据类型，此值将覆盖从类属性读取的数据类型
required	是否为必传参数,false:非必传参数; true:必传参数
position	允许在模型中显示排序属性
hidden	隐藏模型属性，false:不隐藏; true:隐藏
example	属性的示例值
readOnly	指定模型属性为只读，false:非只读; true:只读
reference	指定对应类型定义的引用，覆盖指定的任何其他元数据
allowEmptyValue	允许传空值，false:不允许传空值; true:允许传空值

示例

模型类

@ApiModel(value="user对象", description="登陆用户对象")
public class UserModel {

    @ApiModelProperty(value="用户名", name="username", example="huzhenv5")
    public String username;
    @ApiModelProperty(value="状态", name="state", required=true)
    public Integer state;
    private String password;
    @ApiModelProperty(value="昵称", name="nickName", required=false)
    private String nickName;
    @ApiModelProperty(value="id数组", name="ids")
    public String[] ids;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public Integer getState() {
        return state;
    }

    public void setState(Integer state) {
        this.state = state;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getNickName() {
        return nickName;
    }

    public void setNickName(String nickName) {
        this.nickName = nickName;
    }

    public String[] getIds() {
        return ids;
    }

    public void setIds(String[] ids) {
        this.ids = ids;
    }
}

controller类

@Controller
@RequestMapping("/model")
@Api(tags ="@ApiModel注解示例类")
public class ModelController {

    @RequestMapping(value = "/addtion", method = RequestMethod.POST)
    @ApiOperation("新增用户")
    public UserModel addtion(
            @RequestBody @ApiParam(name="用户对象", value="请求时传入json格式", required=true) UserModel user){
        return new UserModel();
    }

}