From 910985e0ca993e1d54e0e1ad00b16ae3e86a3b0d Mon Sep 17 00:00:00 2001 From: Junling Bu Date: Wed, 1 May 2019 13:47:23 +0800 Subject: [PATCH] =?UTF-8?q?doc:=20=E5=A2=9E=E5=8A=A0=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/README.md | 1 + doc/admin.md | 2 - doc/api.md | 242 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/wxmall.md | 4 - 4 files changed, 243 insertions(+), 6 deletions(-) create mode 100644 doc/api.md diff --git a/doc/README.md b/doc/README.md index 5d7bfe1c..f986e0ef 100644 --- a/doc/README.md +++ b/doc/README.md @@ -4,6 +4,7 @@ * [更新日志](../CHANGELOG.md) * [贡献指南](../CONTRIBUTE.md) * [FAQ](./FAQ.md) +* [API文档](./api.md) * [1. 系统架构](./project.md) * [2. 基础系统](./platform.md) * [3. 小商场](./wxmall.md) diff --git a/doc/admin.md b/doc/admin.md index b18e270f..45fe8af5 100644 --- a/doc/admin.md +++ b/doc/admin.md @@ -21,9 +21,7 @@ * `改善`管理员登录页面打开慢，优化速度 * `改善`地址优化，目前每一次点击都会请求后台，应该缓存已有的数据 * `改善`vue和vue-element-admin等及时更新 -* `功能`系统日志功能 * `功能`系统数据字典功能 -* `功能`系统栏目管理功能 * `功能`支持数据库备份 ## 4.1 litemall-admin-api diff --git a/doc/api.md b/doc/api.md new file mode 100644 index 00000000..d7a54c87 --- /dev/null +++ b/doc/api.md @@ -0,0 +1,242 @@ +# 前后端接口文档 + +本项目前后端接口规范和接口文档。 + +本项目没有采用Swagger技术，开发者可以自行集成。 + +注意： +> 1. 以下API部分基于nideshop开源项目的API设计； +> 2. 以下API是参考API，可能不是很合理，欢迎开发者交流。 +> 3. 接口文档处于开发中，如果发现接口描述和接口实际不对应，欢迎PR或者报告。 + +## 1 前后端接口规范 + +### 1.1 请求格式 + +这里没有采用RESTful风格的接口，而是定义具体语义的接口。 +目前只使用`GET`和`POST`来表示请求内容和更新内容两种语义。 + +#### 1.1.1 GET请求 + + GET API_URL?params + +例如 + + GET /home/index + +或者 + + GET /goods/list?page=1&limit=10 + +#### 1.1.2 POST更新 + + POST API_URL + { + body + } + +例如 + + POST /cart/clear + +或者 + + POST /goods/star + { + id: 1 + } + + +### 1.2 响应格式 + + Content-Type: application/json;charset=UTF-8 + { + body + } + + +而body是存在一定格式的json内容： + + { + errno: xxx, + errmsg: xxx,， + data: {} + } + +#### 1.2.1 失败异常 + + { + errno: xxx, + errmsg: xxx + } + +#### 1.2.1 操作成功 + + { + errno: 0, + errmsg: "成功",， + } + +#### 1.2.3 普通对象 + + { + errno: 0, + errmsg: "成功",， + data: {} + } + +#### 1.2.3 对象数组 + + { + errno: 0, + errmsg: "成功",， + data: { + list: [], + page: xxx, + limit: xxx, + total: xxx + } + } + +list是数组，page、limit和total是分页信息。 + +### 1.3 错误码 + +#### 1.3.1 系统通用错误码 + +#### 1.3.2 商场业务错误码 + +#### 1.3.3 管理后台业务错误码 + +### 1.4 Token + +#### 1.4.1 Header&Token + +#### 1.4.2 商场Header + +#### 1.4.3 管理后台Header + +### 1.5 API文档格式 + +接下来会分别从用户层面和管理员层面构建商场API服务和管理后台API服务。 + +这里定义一个API的格式： + +* 应用场景 +* 接口链接 +* 请求参数 +* 响应内容 +* 错误码 + +## 2 商城API服务 + +### 2.1 安全服务 + +### 2.2 首页服务 + +### 2.3 类目服务 + +### 2.4 商品服务 + +### 2.5 购物车服务 + +### 2.6 订单服务 + +### 2.7 会员服务 + +### 2.8 收货地址服务 + +#### 2.8.1 收货地址列表 + +应用场景 + + 请求用户的收货地址列表 + +接口链接 + + GET /wx/address/list + +请求参数 + + userId: 用户ID + +响应结果 + + { + errno: 0, + errmsg: "成功",， + list: [AddressVo] + page: xx + limit: xx + total: xx + } + + +错误码 + + 略 + +#### 2.8.2 收货地址详情 + +应用场景 + + 请求用户的收货地址详情 + +接口链接 + + GET /wx/address/detail + +请求参数 + + userId: 用户ID + id: 收货地址ID + +响应结果 + + { + errno: 0, + errmsg: "成功",， + data: { + id: 收货地址ID， + name: 收货人， + tel: 手机号 + province: 省级行政区域, + city: 市级行政区域, + county: 区级行政区域, + addressDetail: 具体地址, + areaCode: 地址编码， + postalCode: 邮政编码 + isDefault: 是否默认 + } + } + +错误码 + + 略 + +### 2.9 品牌商服务 + +### 2.10 收藏服务 + +### 2.11 评论服务 + +### 2.12 优惠券服务 + +### 2.13 反馈服务 + +### 2.14 足迹服务 + +### 2.15 团购服务 + +### 2.16 帮助服务 + +### 2.17 搜索服务 + +### 2.18专题服务 + +### 2.18 对象存储服务 + + +## 3 管理后台API服务 + +略 \ No newline at end of file diff --git a/doc/wxmall.md b/doc/wxmall.md index b8086cf4..acb9821f 100644 --- a/doc/wxmall.md +++ b/doc/wxmall.md @@ -12,7 +12,6 @@ 目前发现存在的一些问题： -* `缺失`优惠券功能 * `缺失`商品评价中管理员回复功能，进一步地用户之间相互评价回复 * `缺失`后台服务返回的token存在有效期，小商场应该自动刷新 * `缺失`账号多次登录失败，应该小商城出现图片验证码限制，或者后台账号锁定 @@ -29,9 +28,6 @@ * `改善`个人页面中实现订单部件，显示用户订单数量，同时点击以后跳转到订单的相应页面。 * `改善`商品的订单中支持订单号搜索功能 * `改善`在一些内容比较多的页面中支持“顶部”功能 -* `功能`目前已经有账号登录页面，可以再支持手机短信登录方式。 -* `功能`个人页面支持帮助中心 -* `功能`推荐功能，基于用户的一些信息，在合适的页面给出推荐商品 ## 3.0 小商场环境