秒杀API设计

1. 前言

1.1编写目的

API之主要目的是提供应用程序与开发人员以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。提供API所定义的功能的软件称作此API的实现。API是一种接口，故而是一种抽象。

1.2背景

秒杀系统的秒杀页面以及详情页面的API设计

 

1. 用户接口设计

2.1用户登陆设计

接口：/login/do_login

校验：session

方法：get.post

                                                                                 表3-1 用户登陆请求

参数	类型	是否必须	描述
mobile	String	是	手机号
password	String	是	密码
verifyInput	String	否	验证码
ifyzm	int	否	是否需要验证

 当验证的数据为0是，需要填写验证码，为1时则不需要。

                                                                                 表3-2 用户登陆返回

参数	类型	是否必须	描述
code	int	是	状态
msg	String	是	返回
data	boolean	是	登陆是否成功

登陆成功后token记录到cookie中。

 

1. 商品接口

3.1商品列表

接口：/goods/to_List

校验：session

方法：get post

                                                                                       表4-1商品列表请求

参数	类型	是否必须	描述
goods.id	Long	是	id
goods.stockCount	Integer	是	库存
goods.List	List<GoodVo>	是	列表
goods.goodsname	String	是	名称
goods.goodsImg	String	是	照片
goods.goodsPrice	Double	是	价格
goods.miaoshaPrice	Double	是	秒杀价格

3.2详情接口

接口：/goods/to_detail/{goodsId}

校验：session

方法：get post

                                                                                      表3-2 详情请求

参数	类型	必须	描述
goodsId	Long	是	id

Model进行数据传递goods

                                                                                         表3-3详情返回

参数	类型	必须	描述
goods.id	Long	是	id
goods.stockCount	Integer	是	库存
goods.goodsName	String	是	名称
goods,goodsImg	String	是	照片
goods.goodsPrice	Double	是	原价
goods.startDate	Date	是	秒杀开始时间
miaoshaStatus	int	是	秒杀状态
goods.miaoshaoPrice	Double	是	秒杀价格
remainSeconds	int	是	秒杀倒计时

 

1. 秒杀接口

接口：/miaosha/ do_miaosha

校验：session

方法：get/post

                                                                                       表4-1商品详情请求参数

参数	类型	必须	描述
goodsId	Long	是	id

                                                                                          表4-2用户登陆返回

参数	类型	必须	描述
goods.goods Name	String	是	名称
goods.goodsImg	String	是	图片
orderInfo.goodsPrice	Double	是	订单价格
orderInfo.createDate	Date	是	下单时间
orderInfo.status	Integer	是	订单状态

订单状态：

0：未支付

1：待发货

2：已发货

3：已收货

4：已退款

5：已完成

 

Swagger相关的注解

Web API文档工具列表 Swagger ——baiSwagger框架可以通过代码生du成漂亮的在线API。

直接在Controller类上添加注解，常用的注解如下：

@Api 配置方法zhiAPI

@ApiOperation API的操dao作 GET PUT DELETE POST

@ApiParam API的方法参数描述

 

常用注解 ：

1.@Api()：用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源

 

2.@ApiOperation()：用于方法，表示一个http请求访问该方法的操作

 

3.@ApiModel()：用于响应实体类上，用于说明实体作用

 

4.@ApiModelProperty：用在属性上，描述实体类的属性

 

5.@ApiImplicitParams：用在请求的方法上，包含多@ApiImplicitParam

 

6.@ApiImplicitParam：用于方法，表示单独的请求参数

 

7.@ApiParam()：用于方法，参数，字段说明 表示对参数的要求和说明

 

8.@ApiResponses：用于请求的方法上，根据响应码表示不同响应

一个@ApiResponses包含多个@ApiResponse

 

9.@ApiResponse：用在请求的方法上，表示不同的响应

 

10.@ApiIgnore()：用于类或者方法上，不被显示在页面上