swagger使用说明

controller

• apiController说明 @Api(tags = “controllerClassName”, description = “该controller说明”)

interface

• 传递header使用，如token @ApiImplicitParams({
  @ApiImplicitParam(paramType = “header”, name = “Token”,
  value = “token”, dataType = “String”, required = true)})
• 接口说明,返回说明以及返回数据格式说明 @ApiOperation(response = ResponseData.class,value = “返回说明”)
  • name–参数ming
  • value–参数说明
  • dataType–数据类型
  • paramType–参数类型
  • example–举例说明

param

• 参数传递,用于在url接收使用,也可后面用“,”追加下一个参数 @ApiParam(name = “id”,value = “xxid”, required = true)@RequestParam String id
• 参数传递，用于在url接收使用 Object object
• 参数传递，用于在requestBody中接收使用 @RequestBody Object object，可用@ApiParam做解释说明
• 参数传递，用于在url中按序位接收取用，url为xxx/{id} @PathVariable(“id”) String id
• 参数传递，也可用interface中的@ApiImplicitParams来使用，主要注意paramType的值
  • name–参数名
  • value–参数说明
  • required–是否必填

DTO

• 数据对象描述 @ApiModel(value = “数据对象描述”)
• 对象属性描述 @ApiModelProperty(value = “对象属性描述”, required = true)
• 隐藏不需要字段 @ApiModelProperty(hidden=true)
  • value–字段说明
  • name–重写属性名字
  • dataType–重写属性类型
  • required–是否必填
  • example–举例说明
  • hidden–隐藏

附录1

常用注解说明

• @Api()用于类；
  表示标识这个类是swagger的资源
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

附录2

controller中常用注解替换说明

• @RequestMapping表述此方法或者类的urlHeader
  • value urlHeader
  • method 请求类型
  • consumes 请求数据转码，如MediaTypes.APPLICATION_JSON_UTF8_VALUE
• 替换@PostMapping或者@GetMapping等
• 类上加@RestController返回JSON结果

附录3

• 在DTO中使用@Data注解（lombok.Data），可以不用写get/set方法，eclipse需要导入jar包，idea需要安装lombok插件