Swagger2构建RESTful (二)

Swagger注释API详细说明

详细说明:

作用范围	API	使用位置
对象属性	@ApiModelProperty	用在出入参数对象的字段上
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

一、@ApiImplicitParam

        可用在@ApiImplicitParams注解中，也可以单独使用，指定一个请求参数的各个方面

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交 仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交 仅支持POST
dataType		参数的数据类型 只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

例子:

@ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户编号(必填)", required = true, dataType = "Long", paramType = "path"),
            @ApiImplicitParam(name = "name", value = "用户名称", dataType = "String"),
            @ApiImplicitParam(name = "age", value = "用户年龄", dataType = "Integer"),
            @ApiImplicitParam(name = "user", value = "用户实体User(不填: 默认值)", dataType = "User", defaultValue = "User")
    })

二、@ApiOperation

        我们添加这个注解到任何controller的rest方法上来给方法添加基本的描述

属性	作用
value	接口说明
httpMethod	接口请求方式
response	接口返回参数类型
notes	接口发布说明

例子:

@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")

三、@ApiModelProperty

        这个注解用来在数据模型对象中的属性上添加一些描述,会在Swagger UI中展示模型的属性

属性	作用
value	字段说明
name	重写属性名字
dataType	重写属性类型
required	是否必填
example	举例说明
hidden	隐藏

例子:

public class User implements Serializable{
      private static final long serialVersionUID = 1L;
      @ApiModelProperty(value="用户名",name="username",example="xingguo")
      private String username;
      @ApiModelProperty(value="状态",name="state",required=true)
      private Integer state;
      private String password;
      private String nickName;
      private Integer isDeleted;
 
      @ApiModelProperty(value="id数组",hidden=true)
      private String[] ids;
      private List<String> idList;
     //省略get/set
}

四、@ApiResponse 

        我们添加这个注解到任何controller的rest方法上来给方法添加基本的描述

属性	作用
code	数字, 例如400
message	信息, 例如"请求参数没填好"
response	抛出异常的类

例子:

  @ApiResponses(value = { @ApiResponse(code = 400, message = "Invalid ID supplied"),
      @ApiResponse(code = 404, message = "Pet not found") })
  public Response getPetById(...) {...}

五、@Api

        我们可以添加这个注解在controller上,去添加一个基本的controller说明

例子:

@Api(value = "UserController", description = "user控制器")
@RestController
@RequestMapping(value = "/users") // 通过这里配置使下面的映射都在/users下，可去
public class UserController {
 ...
}