fdzcxy212204238
/
Campus_second-hand_trading_platform
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'd84bb530f7'
${ noResults }
Campus_second-hand_trading_.../document/二手交易平台接口文档.md

36 KiB
Raw Blame History Escape

二手交易平台接口文档

目录

1、接口概述

该接口文档描述了二手交易平台的所有API接口，包括用户管理、商品管理、交易管理、管理员管理等功能。

2、用户接口列表

2.1、用户注册

2.1.1基本信息

  • 请求路径URL：users/register
  • 请求方式：POST
  • 接口描述：该接口用于注册新用户

2.1.2请求参数

  • 请求参数格式：X-www-form-urlencoded `
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
username 用户名 string 是 5-16位非空字符
password 密码 string 是 5-16位非空字符
  • 请求数据样例：
username=sunhehe&password=123456

2.1.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data string 必须 返回的数据
  • 响应数据样例：
{
  "code": 0,
  "message": "操作成功",
  "data": null
}

2.2、用户登录

2.2.1基本信息

  • 请求路径URL：users/login
  • 请求方式：POST
  • 接口描述：该接口用于用户登录

2.2.2请求参数

  • 请求参数格式：X-www-form-yrlencoded
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
username 用户名 string 是 5-16位非空字符
password 密码 string 是 5-16位非空字符
  • 请求数据样例：
username=sunhehe&password=123456

2.2.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data string 必须 返回的数据 jwt 令牌
  • 响应数据样例：
{
  "code": 0,
  "message": "操作成功",
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoiMSIsInVzZXJuYW1lIjoi5byg5LiJIn0sImV4cCI6MTczMDY1MjY4NH0.U9DCkONPv_Nw29WHbpABQ2yRl4LVoQYPpkZ1_qKIR2U"
}

2.2.4备注说明

用户登录成功后，系统会自动下发 JWT 令牌，然后在后续的每次请求中，浏览器都需要在请求头 header 中携带到服务端，请求头的名称为 Authorization ,值为登录时下发的 JWT 令牌。
如果检测到用户未登录，则 http 响应状态码为 401

2.3、获取用户基本信息

2.3.1基本信息

  • 请求路径URL：users/info
  • 请求方式：GET
  • 接口描述：该接口用于获取当前已登陆用户的详细信息

2.3.2请求参数

无

2.3.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data string 必须 返回的数据
--id number 非必须 主键ID
--userna string 非必须 用户名
--nickname string 非必须 昵称
--email string 非必须 邮箱
--userPic string 非必须 头像地址
--createTime string 非必须 创建时间
--updateTime string 非必须 更新时间
  • 响应数据样例：
{
  "code": 0,
  "message'": "操作成功",
  "data": {
    "id": 5,
    "username": "sunhehe",
    "nickname": "",
    "emai1": "",
    "userPic": "",
    "createTime": "2024-11-0322:21:31",
    "updateTime": "2024-11-0322:21:31"
  }
}

2.4、更新用户基本信息

2.4.1基本信息

  • 请求路径URL：/user/update
  • 请求方式：PUT
  • 接口描述：该接口用于更新已登录用户的基本信息（除头像和密码）

2.4.2请求参数

  • 请求参数格式：application/json
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
id 主键ID number 是
username 用户名 string 否 5-16位非空字符
nickname 昵称 string 是 1-10位非空字符
email 邮箱 string 是 满足邮箱格式要求
  • 请求数据样例：
{
  "id": 5,
  "username": "sunhehe",
  "nickname": "澜崽",
  "email": "151037@qq.com"
}

2.4.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data object 非必须 返回的数据
  • 响应数据样例：
{
  "code": 0,
  "message'": "操作成功",
  "data": null
}

2.5、更新用户头像

2.5.1基本信息

  • 请求路径URL：user/updateAvatar
  • 请求方式：PATCH
  • 接口描述：该接口用于更新已登录用户的头像

2.5.2请求参数

  • 请求参数格式：queryString
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
avatarUrl 头像地址 string 是 url地址
  • 请求数据样例：
{
    avatarur1 = https
://haowallpaper.com/link/common/file/previewFileImg/15690537886650688
}

2.5.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data object 非必须 返回的数据
  • 响应数据样例：
{
  "code": 0,
  "message'": "操作成功",
  "data": null
}

2.6、更新用户密码

2.6.1基本信息

  • 请求路径URL：user/updatePwd
  • 请求方式：PATCH
  • 接口描述：该接口用于更新已登录用户的密码

2.6.2请求参数

  • 请求参数格式：application/json
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
old_pwd 原密码 string 是
new_pwd 新密码 string 是
re_pwd 确认新密码 string 是
  • 请求数据样例：
{
  "old_pwd": "123456",
  "new_pwd": "234567",
  "re_pwd": "234567"
}

2.6.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data object 非必须 返回的数据
  • 响应数据样例：
{
  "code": 0,
  "message'": "操作成功",
  "data": null
}

3、商品接口列表

3.1、添加商品

3.1.1基本信息

  • 请求路径URL：product/add
  • 请求方式：POST
  • 接口描述：该接口用于添加新商品

3.1.2请求参数

  • 请求参数格式：application/json
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
name 商品名称 string 是 商品的名称
price 商品价格 number 是 商品的价格（￥）
description 商品描述 string 否 对商品的详细描述
category 商品类别 string 是 商品所属类别
imageUrl 商品图片链接 string 否 商品图片的URL
  • 请求数据样例：
{
  "name": "二手书籍",
  "price": 50,
  "description": "一本很好的二手书籍",
  "category": "书籍",
  "imageUrl": "https://img3m5.ddimg.cn/58/24/27883705-1_e_2.jpg"
}

3.1.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data object 非必须 返回的数据
  • 响应数据样例：
{
  "code": 0,
  "message'": "操作成功",
  "data": null
}

3.2、获取商品列表

3.2.1基本信息

  • 请求路径URL：product/list
  • 请求方式：GET
  • 接口描述：该接口用于获取商品列表

3.2.2请求参数

无

3.2.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data object 非必须 商品列表
--id number 非必须 商品ID
--name string 非必须 商品的名称
--price number 非必须 商品的价格（￥）
--description string 非必须 商品描述
--category string 非必须 商品类别
--imageUrl string 非必须 商品图片
  • 响应数据样例：
{
  "code": 0,
  "message'": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "二手书籍",
      "price": 50,
      "description": "一本很好的二手书籍",
      "category": "书籍",
      "imageUrl": "http://example.com/image.jpg"
    },
    {
      "id": 2,
      "name": "二手台灯",
      "price": 300,
      "description": "状态良好的二手台灯",
      "category": "杂物",
      "imageUrl": "http://example.com/image2.jpg"
    }
  ]
}

3.3、获取商品详情

3.3.1基本信息

  • 请求路径URL：product/detail/{id}
  • 请求方式：GET
  • 接口描述：该接口用于获取指定商品的详细信息

3.3.2请求参数

  • 请求参数格式：application/json
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
id 商品ID number 必须 要获取详情的商品ID
  • 请求数据样例：
{
  "id": 1
}

3.3.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data object 非必须 商品详细信息
  • 响应数据样例：
{
  "code": 0,
  "message'": "操作成功",
  "data": {
    "id": 1,
    "name": "二手书籍",
    "price": 50,
    "description": "一本很好的二手书籍",
    "category": "书籍",
    "imageUrl": "http://example.com/image.jpg"
  }
}

3.4、删除商品

3.4.1基本信息

  • 请求路径URL：product/delete/{id}
  • 请求方式：DELETE
  • 接口描述：该接口用于删除指定商品

3.4.2请求参数

  • 请求参数格式：application/json
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
id 商品ID number 是 要删除的商品ID
  • 请求数据样例：
{
  "id": 2
}

3.4.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data object 非必须 返回的数据
  • 响应数据样例：
{
  "code": 0,
  "message'": "操作成功",
  "data": null
}

3.5、搜索商品

3.5.1基本信息

  • 请求路径URL：/product/search
  • 请求方式：GET
  • 接口描述：该接口用于根据关键词搜索商品。可以根据商品名称、分类、描述等信息进行模糊查询。

3.5.2请求参数

  • 请求参数格式：application/json
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
keyword 搜索关键词（商品名称、描述等） string 是 用于搜索商品的关键词，支持模糊查询。
category 商品分类 string 否 可选，指定商品类别进行筛选，若不提供则不筛选类别。
page 页码（分页查询） number 否 默认值为1，表示第一页。
pageSize 每页显示的商品数量 number 否 默认值为20，最大值为100，表示每页显示的商品数。
  • 请求数据样例：
{
  "keyword": "手机",
  "category": "电子产品",
  "page": 1,
  "pageSize": 20
}

3.5.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 - 成功，1 - 失败
message string 非必须 提示信息
data object 必须 返回的数据，包含商品列表信息
total number 必须 符合条件的商品总数
page number 必须 当前页码
pageSize number 必须 每页商品数
  • 响应数据样例：
{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "productId": 12345,
      "name": "二手iPhone 12",
      "category": "电子产品",
      "price": 3000,
      "description": "几乎全新，屏幕完好，原装配件",
      "imageUrl": "http://example.com/iphone12.jpg",
      "sellerId": 67890,
      "sellerName": "张三"
    },
    {
      "productId": 67890,
      "name": "二手MacBook Pro",
      "category": "电子产品",
      "price": 4500,
      "description": "配置高，性能稳定，电池寿命长",
      "imageUrl": "http://example.com/macbookpro.jpg",
      "sellerId": 12345,
      "sellerName": "李四"
    }
  ],
  "total": 50,
  "page": 1,
  "pageSize": 20
}

3.6、更新商品

3.6.1基本信息

  • 请求路径URL：/product/update/{id}
  • 请求方式：POST
  • 接口描述：该接口用于根据关键词更新商品。

3.6.2请求参数

  • 请求参数格式：application/json
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
id 商品ID number 是 要更新的商品ID。
name 商品名称 string 否 商品的名称。
category 商品分类 string 否 商品的分类（可选）。
price 商品价格 number 否 商品的价格。
description 商品描述 string 否 商品的描述信息。
imageUrl 商品图片URL string 否 商品图片的URL。
  • 请求数据样例：
{
  "id": 12345,
  "name": "二手iPhone 12 Pro",
  "category": "电子产品",
  "price": 3500,
  "description": "几乎全新，屏幕无划痕，配件齐全",
  "imageUrl": "http://example.com/iphone12pro.jpg"
}

3.6.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 - 成功，1 - 失败
message string 非必须 提示信息
data object 必须 返回的数据，包含商品列表信息
  • 响应数据样例：
{
  "code": 0,
  "message": "商品更新成功",
  "data": {
    "productId": 12345,
    "name": "二手iPhone 12 Pro",
    "category": "电子产品",
    "price": 3500,
    "description": "几乎全新，屏幕无划痕，配件齐全",
    "imageUrl": "http://example.com/iphone12pro.jpg",
    "sellerId": 67890,
    "sellerName": "张三"
  }
}

4、交易管理

4.1、创建订单

4.1.1基本信息

  • 请求路径URL：order/create
  • 请求方式：POST
  • 接口描述：该接口用于创建新订单

4.1.2请求参数

  • 请求参数格式：application/json
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
  • 请求数据样例：
{
}

4.1.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data object 非必须 返回的数据
  • 响应数据样例：
{
  "code": 0,
  "message'": "操作成功",
  "data": null
}

4.2、获取订单列表

4.2.1基本信息

  • 请求路径URL：order/list
  • 请求方式：GET
  • 接口描述：该接口用于获取用户的订单列表

4.2.2请求参数

无

4.2.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data object 非必须 返回的数据
  • 响应数据样例：
{
  "code": 0,
  "message'": "操作成功",
  "data": null
}

4.3、获取订单详情

4.3.1基本信息

  • 请求路径URL：order/detail/{id}
  • 请求方式：GET
  • 接口描述：该接口用于获取指定订单的详细信息

4.3.2请求参数

  • 请求参数格式：application/json
  • 请求参数说明： 无
  • 请求数据样例： 无

4.3.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 -成功，1 -失败
message string 非必须 提示信息
data object 非必须 返回的数据
  • 响应数据样例：
{
  "code": 0,
  "message'": "操作成功",
  "data": null
}

4.4、取消订单

4.4.1基本信息

  • 请求路径URL：/order/cancel/{id}
  • 请求方式：DELETE
  • 接口描述：该接口用于取消指定订单。通过订单ID（id）来唯一标识待取消的订单。如果订单状态允许取消（例如未支付或待发货），则可以成功取消订单。

4.4.2请求参数

  • 请求参数格式：application/json
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
id 订单ID number 是 订单的唯一标识符，用于指定需要取消的订单。

注：id是URL路径的一部分，不是请求体中的参数。

  • 请求数据样例： 无

4.4.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 - 成功，1 - 失败
message string 必须 提示信息
data object 非必须 返回的数据，通常为空
  • 响应数据样例：
//取消订单成功
{
  "code": 0,
  "message": "订单取消成功",
  "data": null
}

// 取消订单失败（例如订单已发货或已完成）
{
  "code": 1,
  "message": "订单无法取消，订单已发货",
  "data": null
}

5、管理员管理

5.1、管理员登录

5.1.1基本信息

  • 请求路径URL：/admin/login
  • 请求方式：POST
  • 接口描述：管理员登录接口，用于验证管理员身份并返回登录信息。

5.1.2请求参数

  • 请求参数格式：application/x-www-form-urlencoded
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
username 用户名 string 是 管理员的用户名，5-16位
password 密码 string 是 管理员的密码，5-16位
  • 请求数据样例：
username=sunhehe&password=123456

5.1.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 - 成功，1 - 失败
message string 非必须 提示信息，登录成功或失败的描述
data object 非必须 包含管理员的登录令牌等信息
  • 响应数据样例：
{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "abcd1234xyz",
    "adminId": "admin_001",
    "role": "super_admin"
  }
}

5.2、用户管理

5.2.1基本信息

  • 请求路径URL：/admin/user/list
  • 请求方式：GET
  • 接口描述：管理员查看用户列表。

5.2.2请求参数

  • 请求参数格式：application/x-www-form-urlencoded
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
page 页码 number 否 默认为1，分页
size 每页数量 number 否 默认为10，分页
  • 请求数据样例：

5.2.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 - 成功，1 - 失败
message string 非必须 提示信息
data object[] 必须 用户列表数据
data[] object 必须 每个用户的详细信息
data[].id string 必须 用户ID
data[].username string 必须 用户名
data[].email string 非必须 用户邮箱
data[].status string 非必须 用户状态 (active/inactive)
  • 响应数据样例：
{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "id": "user_001",
      "username": "john_doe",
      "email": "john.doe@example.com",
      "status": "active"
    },
    {
      "id": "user_002",
      "username": "jane_smith",
      "email": "jane.smith@example.com",
      "status": "inactive"
    }
  ]
}

5.3、商品管理

5.3.1基本信息

  • 请求路径URL：/admin/product/list
  • 请求方式：GET
  • 接口描述：管理员查看所有商品信息。

5.3.2请求参数

  • 请求参数格式：application/x-www-form-urlencoded
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
page 页码 number 否 默认为1，分页
size 每页数量 number 否 默认为10，分页
  • 请求数据样例：

5.3.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 - 成功，1 - 失败
message string 非必须 提示信息
data object[] 必须 商品列表数据
data[] object 必须 每个商品的详细信息
data[].id string 必须 商品ID
data[].name string 必须 商品名称
data[].price number 必须 商品价格
data[].quantity number 必须 商品库存数量
  • 响应数据样例：
{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "id": "prod_001",
      "name": "二手笔记本电脑",
      "price": 2999.99,
      "quantity": 10
    },
    {
      "id": "prod_002",
      "name": "二手手机",
      "price": 1599.99,
      "quantity": 25
    }
  ]
}

5.4、订单管理

5.4.1基本信息

  • 请求路径URL：/admin/order/list
  • 请求方式：GET
  • 接口描述：管理员查看所有订单信息。

5.4.2请求参数

  • 请求参数格式：application/x-www-form-urlencoded
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
page 页码 number 否 默认为1，分页
size 每页数量 number 否 默认为10，分页
  • 请求数据样例：

5.4.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 - 成功，1 - 失败
message string 非必须 提示信息
data object[] 必须 订单列表数据
data[] object 必须 每个订单的详细信息
data[].orderId string 必须 订单ID
data[].userId string 必须 用户ID
data[].productId string 必须 商品ID
data[].quantity number 必须 商品数量
data[].status string 必须 订单状态 (pending/paid/shipped)
  • 响应数据样例：
{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "orderId": "order_001",
      "userId": "user_001",
      "productId": "prod_001",
      "quantity": 1,
      "status": "paid"
    },
    {
      "orderId": "order_002",
      "userId": "user_002",
      "productId": "prod_002",
      "quantity": 2,
      "status": "shipped"
    }
  ]
}

5.5、退出模块

5.5.1基本信息

  • 请求路径URL：/admin/logout
  • 请求方式：POST
  • 接口描述：管理员退出登录接口，用于清除

5.5.2请求参数

  • 请求参数格式：application/json
  • 请求参数说明：
参数名称 说明 类型 是否必须 备注
token 登录令牌 string 是 管理员登录时获取的token，用于身份验证
  • 请求数据样例： 无

5.5.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 - 成功，1 - 失败
message string 非必须 提示信息
  • 响应数据样例：
{
  "code": 0,
  "message": "退出登录成功"
}

6、其他接口

6.2、用户反馈

6.2.1基本信息

  • 请求路径URL：/feedback/submit
  • 请求方式：POST
  • 接口描述：该接口用于提交用户反馈，用户可以通过此接口提交对平台的建议、问题或其他反馈。

6.2.2请求参数

  • 请求参数格式：application/json

  • 请求参数说明： | 参数名称 | 说明 | 类型 | 是否必须 | **备注

    **
    userId 用户ID number 是 提交反馈的用户的ID，用于标识反馈来源。
    content 反馈内容 string 是 用户提交的反馈内容，字数限制为500个字符。
    contactInfo 联系方式（可选） string 否 可选，用户希望被平台联系的方式（如电话、邮箱等）。

  • 请求数据样例：

{
  "userId": 12345,
  "content": "平台的商品搜索功能有些慢，希望能够优化。",
  "contactInfo": "example@example.com"
}

6.2.3响应数据

  • 响应数据类型：application/json
  • 响应参数说明：
名称 类型 是否必须 备注
code number 必须 响应码，0 - 成功，1 - 失败
message string 非必须 提示信息
data object 非必须 返回的数据，通常为空
  • 响应数据样例：
{
  "code": 0,
  "message": "反馈提交成功",
  "data": null
}