swagger2配置详解

1.写在controller上的注解

1.1 @Api

代码

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

public class UserController

属性解析

注解属性	类型	描述
tags	String[]	控制器标签。
description	String	控制器描述 （该字段被申明为过期）

2.写在方法上的注解

2.1 接口方法的描述

@ApiOperation 主要属性

代码

@PostMapping(value = "/login")
    @ApiOperation(value = "登录接口",notes = "登录接口",httpMethod = "POST",responseContainer="登录成功，登录失败")
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 10000, message = "用户名验证码为空"),
            @ApiResponse(code = 10001, message = "验证码不正确"),
            @ApiResponse(code = 10002, message = "验证码已失效"),
            @ApiResponse(code = 10004, message = "登录错误次数超过五次"),
            @ApiResponse(code = 10005, message = "用户名或密码错误"),
            @ApiResponse(code = 10006, message = "账号被冻结,请联系管理员")
    })
    public  ResponseEntity<Message<SystemAccountBean>> login(@RequestBody SystemAccountBeanVO systemAccountBean, HttpServletRequest request) {

        return ResponseEntity.ok(new Message(loginService.login(systemAccountBean, request)));

    }

属性解析

注解属性	类型	描述
value	String	接口说明。
notes	String	接口发布说明。
tags	Stirng[]	标签。
response	Class<?>	接口返回类型。
httpMethod	String	接口请求方式。

@ApiIgnore

Swagger 文档不会显示拥有该注解的接口

@ApiImplicitParams

用于描述接口的非对象参数集

@ApiImplicitParam

用于描述接口的非对象参数，一般与 @ApiImplicitParams 组合使用。

@ApiImplicitParam

代码示例

@ApiImplicitParams({
            @ApiImplicitParam(name = "accountId", value = "账户ID", dataType = "string", paramType = "query", example = "xingguo"),
    })
    public ResultMsgBean<List<SystemMenuBean>> queryForMenuListByAccountId() {
        return systemMenuBean;
    }

主要属性

注解属性	描述
paramType	查询参数类型，实际上就是参数放在那里。取值： path：以地址的形式提交数据，根据 id查询用户的接口就是这种形式传参。 query：Query string 的方式传参。 header：以流的形式提交。 form：以 Form 表单的形式提交。
dataType	参数的数据类型。取值：Long String
name	参数名字。
value	参数意义的描述。
required	是否必填。取值：true：必填参数。false：非必填参数。

3.写在实体类上的注解

3.1 描述

@ApiModel:

可设置接口相关实体的描述。

@ApiModelProperty:

可设置实体属性的相关描述

3.2 代码示例

@ApiModel(description= "账户信息类")
public class SystemAccountBean extends CustomerPersonBean {
	/** 帐号序号 */
	@ApiModelProperty(value="帐号序号")
	private String accountId;
}

3.3 @ApiModelProperty属性说明

注解属性	类型	描述
value	String	字段说明。
name	String	重写字段名称。
dataType	Stirng	重写字段类型。
required	boolean	是否必填。
example	Stirng	举例说明。
hidden	boolean	是否在文档中隐藏该字段。
allowEmptyValue	boolean	是否允许为空。
allowableValues	String	该字段允许的值，当我们 API 的某个参数为枚举类型时， 使用这个属性就可以清楚地告诉 API 使用者该参数所能允许传入的值。