Swagger注解详解
1.1 @Api
用在类上,说明该类的作用
比如说:@Api(value = “UserController”, description = “用户相关api”)
@Api(value="物料")
@Controller
@RequestMapping("material")
public class MaterialController {
@Resource
protected MaterialService materialService;
@ApiOperation(httpMethod="POST", value="创建物料")
@RequestMapping("service/create")
@ResponseBody
public ResponseResult create(@RequestBody Material material) {
//
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Api(value="物料")
@Controller
@RequestMapping("material")
publicclassMaterialController{
@Resource
protectedMaterialServicematerialService;
@ApiOperation(httpMethod="POST",value="创建物料")
@RequestMapping("service/create")
@ResponseBody
publicResponseResultcreate(@RequestBodyMaterialmaterial){
//
}
}
1.2 @ApiOperation
用在方法上,说明方法的作用
比如说:
@ApiOperation(value = “查找用户”, notes = “查找用户”, httpMethod = “GET”, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@ApiOperation(httpMethod="POST", value="查询物料")
@RequestMapping("service/findByPage")
@ResponseBody
public ResponseResult> findByPage(
@ApiParam(value="所在页",defaultValue="0")
@RequestParam(defaultValue="0") int pageNo,
@ApiParam(value="每页数量",defaultValue="10")
@RequestParam(defaultValue="10") int pageSize,
@ApiParam(value="查询条件,属性名请参考 Material")
@RequestBody(required=false) List params) {
//处理
}
1
2
3
4
5
6
7
8
9
10
11
12
13
@ApiOperation(httpMethod="POST",value="查询物料")
@RequestMapping("service/findByPage")
@ResponseBody
publicResponseResult>findByPage(
@ApiParam(value="所在页",defaultValue="0")
@RequestParam(defaultValue="0")intpageNo,
@ApiParam(value="每页数量",defaultValue="10")
@RequestParam(defaultValue="10")intpageSize,
@ApiParam(value="查询条件,属性名请参考 Material")
@RequestBody(required=false)Listparams){
//处理
}
1.3 @ApiImplicitParams
用在方法上包含一组参数说明
paramType:参数放在哪个地方
header–>请求参数的获取:@RequestHeader
query–>请求参数的获取:@RequestParam
path(用于restful接口)–>请求参数的获取:@PathVariable
body(不常用)
form(不常用)
name:参数名
dataType:参数类型
required:参数是否必须传
value:参数的意思
defaultValue:参数的默认值
比如说:
@ApiOperation(httpMethod = "GET", value = "获取店铺列表", response = ResponseResult.class,
notes = "实现方式可以用get请求,直接传当前页以及页码大小以及排序等:http://localhost:8888/shop/find?sort=cellphone,asc&sort=shopFullName,desc&page=1&size=10")
@ApiImplicitParams({
@ApiImplicitParam(name = "province",required = false, value = "省",paramType ="query", dataType = "String"),
@ApiImplicitParam(name = "city",required = false, value = "市",paramType ="query", dataType = "String"),
@ApiImplicitParam(name = "county",required = false, value = "县",paramType ="query", dataType = "String"),
@ApiImplicitParam(name = "pageable",required = false, value = "分页,排序对象",paramType ="body", dataType = "Pageable")
})
@ResponseBody
@RequestMapping(value = { "/findAll" }, method = { RequestMethod.GET, RequestMethod.POST })
public ResponseResult> findAll(
@RequestParam(required = false) String province,
@RequestParam(required = false) String city,
@RequestParam(required = false) String county,
@PageableDefault(sort = { "id" }, direction = Sort.Direction.ASC) Pageable pageable) {
//处理逻辑
return ResponseResult.success(shopList);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
@ApiOperation(httpMethod="GET",value="获取店铺列表",response=ResponseResult.class,
notes="实现方式可以用get请求,直接传当前页以及页码大小以及排序等:http://localhost:8888/shop/find?sort=cellphone,asc&sort=shopFullName,desc&page=1&size=10")
@ApiImplicitParams({
@ApiImplicitParam(name="province",required=false,value="省",paramType="query",dataType="String"),
@ApiImplicitParam(name="city",required=false,value="市",paramType="query",dataType="String"),
@ApiImplicitParam(name="county",required=false,value="县",paramType="query",dataType="String"),
@ApiImplicitParam(name="pageable",required=false,value="分页,排序对象",paramType="body",dataType="Pageable")
})
@ResponseBody
@RequestMapping(value={"/findAll"},method={RequestMethod.GET,RequestMethod.POST})
publicResponseResult>findAll(
@RequestParam(required=false)Stringprovince,
@RequestParam(required=false)Stringcity,
@RequestParam(required=false)Stringcounty,
@PageableDefault(sort={"id"},direction=Sort.Direction.ASC)Pageablepageable){
//处理逻辑
returnResponseResult.success(shopList);
}
1.4 @ApiResponses
@ApiResponses用于表示一组响应
1.5 @ApiResponse
1.6 @ApiModel
描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModel(value = “用户实体类”)
@ApiModel(value = "优惠劵信息")
@Entity
@Table(name = "coupon_info")
public class CouponInfo implements Serializable {
}
1
2
3
4
5
6
@ApiModel(value="优惠劵信息")
@Entity
@Table(name="coupon_info")
publicclassCouponInfoimplementsSerializable{
}
1.7 @ApiModelProperty
描述一个model的属性
@ApiModelProperty(value = “登录用户”)
package com.souvc.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
import java.util.Date;
@ApiModel(value="物料")
public class Material implements Serializable {
@ApiModelProperty("主键")
private String id;
@ApiModelProperty("项目ID")
private String projectId;
@ApiModelProperty("公司Id")
private String companyId;
//get,set
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
packagecom.souvc.entity;
importio.swagger.annotations.ApiModel;
importio.swagger.annotations.ApiModelProperty;
importjava.io.Serializable;
importjava.util.Date;
@ApiModel(value="物料")
publicclassMaterialimplementsSerializable{
@ApiModelProperty("主键")
privateStringid;
@ApiModelProperty("项目ID")
privateStringprojectId;
@ApiModelProperty("公司Id")
privateStringcompanyId;
//get,set
}
如果您认为本教程质量不错,读后觉得收获很大,预期工资能蹭蹭蹭的往上涨,那么不妨小额赞助我一下,让我有动力继续写出高质量的教程。