swagger注解说明_Swagger注解详解

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

}

如果您认为本教程质量不错，读后觉得收获很大，预期工资能蹭蹭蹭的往上涨，那么不妨小额赞助我一下，让我有动力继续写出高质量的教程。