1. 电商管理后台 API 接口文档

本文基础结构来源于“黑马程序员课程–‘VUE全家桶’中,所使用的后端API文档,原课程中使用的时Node.js的项目,楼主在将其使用SpringBoot重新构建之后,编写了如下接口文档,重构的源码,将会在后期给出,重构的教程,我会在后期整理成一篇,SpringBoot开发API接口的系列教程。希望对初学者能够有所帮助。”

Swagger2 API文档地址

码云源码地址

1.1. API V1 接口说明

  • 接口基准地址:http://127.0.0.1:8081/api/
  • 服务端已开启 CORS 跨域支持
  • API 认证统一使用 Token 认证
  • 需要授权的 API ,必须在请求头中使用 token 字段提供 token 令牌
  • 使用 HTTP Status Code 标识状态
  • 数据返回格式统一使用 JSON

1.1.1. 支持的请求方法

  • GET(SELECT):从服务器取出资源(一项或多项)。
  • POST(CREATE):在服务器新建一个资源。

1.1.2. 通用返回状态说明

状态码含义说明
101无token,请登录后操作!
102用户不存在,请重新登录!
200请求成功
201创建成功
202创建失败
203修改成功
204修改失败
205删除成功
206删除失败
207查询成功
208查询失败
400请求的地址不存在或者包含不支持的参数
401未授权
403被禁止访问
404请求的资源不存在
500内部错误

1.2. 登录

1.2.1. 登录验证接口

  • 请求路径:mg_login
  • 请求方法:post
  • 请求参数
参数名参数说明备注
mgName用户名不能为空
mgPwd密码不能为空
  • 响应参数
参数名参数说明备注
mgId用户 ID
roleId用户角色 ID
mgName用户名
mgMobile手机号
mgEmail邮箱
token令牌基于 jwt 的令牌
  • 响应数据
{
  "data": {
    "total": 6,
    "list": [
      {
        "mgId": 500,
        "mgName": "admin",
        "mgPwd": "$2y$10$sZlpZNoLAnoD1DtYO9REAODCPkpMb5bwl4oMzrMvJa83k9BY3KRwq",
        "mgTime": 1486720211,
        "roleId": 0,
        "mgMobile": "18088083365",
        "mgEmail": "adsfad@qq.com",
        "mgState": 1
      }
    ],
    "pageNum": 1,
    "pageSize": 1
  },
  "meta": {
    "msg": "请求成功!",
    "status": 200
  }
}

1.3. 用户管理

1.3.1. 用户数据列表

  • 请求路径:/manager/getByParam
  • 请求方法:post
  • 请求参数
参数名参数说明备注
mgName查询参数可以为空
pageNum当前页码不能为空
pageSize每页显示条数不能为空
  • 响应参数
参数名参数说明备注
total总记录数
pageNum当前页码
list用户数据集合
  • 响应数据
{
  "data": {
    "total": 1,
    "list": [
      {
        "mgId": 511,
        "mgName": "test",
        "mgPwd": "test",
        "mgTime": 1,
        "roleId": 0,
        "mgMobile": "1",
        "mgEmail": "1",
        "mgState": 1
      }
    ],
    "pageNum": 1,
    "pageSize": 1,
    "size": 1
  },
  "meta": {
    "msg": "请求成功!",
    "status": 200
  }
}

1.3.2. 添加用户

  • 请求路径:manager/add
  • 请求方法:post
  • 请求参数
参数名参数说明备注
mgName用户名称不能为空
mgPwd用户密码不能为空
mgEmail邮箱可以为空
mgMobile手机号可以为空
  • 响应参数
参数名参数说明备注
mgId用户 ID
roleId用户角色 ID
mgName用户名
mgMobile手机号
mgEmail邮箱
  • 响应数据
{
  "data": {
    "mgId": 512,
    "mgName": "asd",
    "mgPwd": "123456",
    "mgTime": "2020-02-18 14:43:28",
    "roleId": null,
    "mgMobile": "18088083365",
    "mgEmail": "1757895437@qq.com",
    "mgState": null
  },
  "meta": {
    "msg": "请求成功!",
    "status": 200
  }
}

1.3.3. 修改用户状态

  • 请求路径:manager/state
  • 请求方法:put
  • 请求参数
参数名参数说明备注
mgId管理员ID不能为空携带在url中
mgState管理员状态不能为空携带在url中,'1’为启用,‘0’为停用
  • 响应数据
{
  "data": {
    "mgId": "511",
    "mgName": "test",
    "mgPwd": "test",
    "mgTime": "1",
    "roleId": 0,
    "mgMobile": "1",
    "mgEmail": "1",
    "mgState": 0
  },
  "meta": {
    "msg": "修改成功",
    "status": 203
  }
}

1.3.4. 根据 ID 查询用户信息

  • 请求路径:manager/getById
  • 请求方法:get
  • 请求参数
参数名参数说明备注
mgId管理员 ID不能为空携带在url中
  • 响应参数
参数名参数说明备注
mgId用户 ID
roleId角色 ID
mgMobile手机号
mgEmail邮箱
  • 响应数据
{
  "data": {
    "mgId": "511",
    "mgName": "test",
    "mgPwd": "test",
    "mgTime": "1",
    "roleId": 0,
    "mgMobile": "1",
    "mgEmail": "1",
    "mgState": 0
  },
  "meta": {
    "msg": "查询成功",
    "status": 207
  }
}

1.3.5. 编辑用户提交

  • 请求路径:manager/updById
  • 请求方法:put
  • 请求参数
参数名参数说明备注
mgId管理员 id不能为空 参数是url参数:id
mgEmail邮箱可以为空
mgMobile手机号可以为空
  • 响应参数
参数名参数说明备注
mgId用户 ID
roleId角色 ID
mgMobile手机号
mgEmail邮箱
  • 响应数据
/* 200表示成功,500表示失败 */
{
  "data": {
    "mgId": "511",
    "mgName": "test",
    "mgPwd": "test",
    "mgTime": "1",
    "roleId": 0,
    "mgMobile": "12312312312",
    "mgEmail": "123@123.com",
    "mgState": 0
  },
  "meta": {
    "msg": "修改成功",
    "status": 203
  }
}

1.3.6. 删除单个用户

  • 请求路径:manager/delById
  • 请求方法:delete
  • 请求参数
参数名参数说明备注
mgId管理员id不能为空参数是url参数:id
  • 响应参数
  • 响应数据
{
  "data": null,
  "meta": {
    "msg": "删除成功",
    "status": 205
  }
}

1.3.7. 分配用户角色

  • 请求路径:manager/updRole
  • 请求方法:put
  • 请求参数
参数名参数说明备注
mgId管理员 ID不能为空参数是url参数:id
roleId角色 id不能为空参数body参数
  • 响应参数
参数名参数说明备注
mgId管理员 ID
roleId角色 id
mgMobile手机号
mgEmail邮箱
  • 响应数据
{
  "data": {
    "mgId": "c4bc207e-828a-46b4-936b-0674cb1a0f2d",
    "mgName": "manager",
    "mgPwd": "manager",
    "mgTime": "2020-02-18 16:16:32",
    "roleId": "31",
    "mgMobile": "11111111111",
    "mgEmail": "111@111.com",
    "mgState": 1
  },
  "meta": {
    "msg": "修改成功",
    "status": 203
  }
}

1.4. 权限管理

1.4.1. 所有权限列表

  • 请求路径:/rights
  • 请求方法:get
  • 请求参数
参数名参数说明备注
type类型值 list 或 tree , list 列表显示权限, tree 树状显示权限,参数是url参数:type
  • 响应参数
参数名参数说明备注
psId权限 ID
psName权限说明
psLevel权限层级
psPid权限父 ID
path对应访问路径
  • 响应数据 type=list
  {
  "data": [
    {
      "psId": "101",
      "psName": "商品管理",
      "psPid": "0",
      "psC": "",
      "psA": "",
      "psLevel": "0",
      "path": "goods",
      "children": null
    },
    {
      "psId": "102",
      "psName": "订单管理",
      "psPid": "0",
      "psC": "",
      "psA": "order",
      "psLevel": "0",
      "path": "orders",
      "children": null
    }
  ],
  "meta": {
    "msg": "查询成功",
    "status": 207
  }
}

type=tree

 {
  "data": [
    {
      "psId": "101",
      "psName": "商品管理",
      "psPid": "0",
      "psC": "",
      "psA": "",
      "psLevel": "0",
      "children": [
        {
          "psId": "104",
          "psName": "商品列表",
          "psPid": "101",
          "psC": "Goods",
          "psA": "index",
          "psLevel": "1",
          "children": [
            {
              "psId": "105",
              "psName": "添加商品",
              "psPid": "104",
              "psC": "Goods",
              "psA": "tianjia",
              "psLevel": "2",
              "children": []
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "msg": "查询成功",
    "status": 207
  }
}

1.4.2. 左侧菜单权限

  • 请求路径:menus
  • 请求方法:get
  • 响应数据
{
  "data": [
    {
      "psId": "101",
      "psName": "商品管理",
      "psPid": "0",
      "psC": "",
      "psA": "",
      "psLevel": "0",
      "path": "goods",
      "children": [
        {
          "psId": "104",
          "psName": "商品列表",
          "psPid": "101",
          "psC": "Goods",
          "psA": "index",
          "psLevel": "1",
          "path": "goods",
          "children": null
        }
      ]
    }
  ],
  "meta": {
    "msg": "查询成功",
    "status": 207
  }
}
me="t18">1.5. 角色管理

1.5.1. 角色列表

  • 请求路径:roles/getRoleList

  • 请求方法:get

  • 响应数据说明

    • 第一层为角色信息
    • 第二层开始为权限说明,权限一共有 3 层权限
    • 最后一层权限,不包含 children 属性
  • 响应数据

{
    "data": [
        {
            "id": 30,
            "roleName": "主管",
            "roleDesc": "技术负责人",
            "children": [
                {
                    "id": 101,
                    "authName": "商品管理",
                    "path": null,
                    "children": [
                        {
                            "id": 104,
                            "authName": "商品列表",
                            "path": null,
                            "children": [
                                {
                                    "id": 105,
                                    "authName": "添加商品",
                                    "path": null
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "meta": {
        "msg": "获取成功",
        "status": 200
    }
}

1.5.2. 添加角色

  • 请求路径:roles/addRole
  • 请求方法:post
  • 请求参数
参数名参数说明备注
roleName角色名称不能为空
roleDesc角色描述可以为空
  • 响应参数
参数名参数说明备注
roleId角色 ID
roleName角色名称
roleDesc角色描述
  • 响应数据
{
    "data": {
        "roleId": 40,
        "roleName": "admin2",
        "roleDesc": "admin2Desc"
    },
    "meta": {
        "msg": "创建成功",
        "status": 201
    }
}

1.5.3. 根据 ID 查询角色

  • 请求路径:roles/getById
  • 请求方法:get
  • 请求参数
参数名参数说明备注
roleId角色 ID不能为空携带在url中
  • 响应参数
参数名参数说明备注
roleId角色 ID
roleName角色名称
roleDesc角色描述
  • 响应数据
{
  "data": {
    "roleId": "30",
    "roleName": "主管",
    "psIds": "101,0,104,116,115,142,143,121,122,123,149,102,107,109,103,111,129,130,134,135,138,140,141,112,147,125,110,131,132,133,136,137,145,146,148",
    "psCa": "Goods-index,Goods-tianjia,Category-index,Order-showlist,Brand-index",
    "roleDesc": "技术负责人"
  },
  "meta": {
    "msg": "查询成功",
    "status": 207
  }
}

1.5.4. 编辑提交角色

  • 请求路径:roles/update
  • 请求方法:post
  • 请求参数
参数名参数说明备注
roleId角色 ID不能为空携带在url中
roleName角色名称不能为空
roleDesc角色描述可以为空
  • 响应数据
{
  "data": {
    "roleId": "30",
    "roleName": "测试aa",
    "psIds": "101,0,104,116,115,142,143,121,122,123,149,102,107,109,103,111,129,130,134,135,138,140,141,112,147,125,110,131,132,133,136,137,145,146,148",
    "psCa": "Goods-index,Goods-tianjia,Category-index,Order-showlist,Brand-index",
    "roleDesc": "测试"
  },
  "meta": {
    "msg": "修改成功",
    "status": 203
  }
}

1.5.5. 删除角色

  • 请求路径:roles/del
  • 请求方法:get
  • 请求参数
参数名参数说明备注
roleId角色 ID不能为空携带在url中
  • 响应数据
{
  "data": null,
  "meta": {
    "msg": "删除成功",
    "status": 205
  }
}

1.5.6. 角色授权

  • 请求路径:roles/setRights
  • 请求方法:post
  • 请求参数:通过 请求体 发送给后端
参数名参数说明备注
roleId角色 ID不能为空携带在url中
psIds权限 ID 列表(字符串), 分割的权限 ID 列表(获取所有被选中、叶子节点的key和半选中节点的key, 包括 1,2,3级节点)
  • 响应数据
{
  "data": {
    "roleId": "41",
    "roleName": "dsdf",
    "psIds": "105,142,101,104,115",
    "psCa": null,
    "roleDesc": "sf "
  },
  "meta": {
    "msg": "修改成功",
    "status": 203
  }
}

1.5.7. 删除角色指定权限

  • 请求路径:/roles/delRights

  • 请求方法:get

  • 请求参数

参数名参数说明备注
roleId角色 ID不能为空携带在url中
rightId权限 ID不能为空携带在url中
  • 响应数据说明

    • 返回的data, 是当前角色下最新的权限数据
  • 响应数据

  • {
      "data": [
        {
          "psId": "101",
          "psName": "商品管理",
          "psPid": "0",
          "psC": "",
          "psA": "",
          "psLevel": "0",
          "path": null,
          "children": [
            {
              "psId": "115",
              "psName": "分类参数",
              "psPid": "101",
              "psC": "Type",
              "psA": "index",
              "psLevel": "1",
              "path": null,
              "children": [
                {
                  "psId": "142",
                  "psName": "获取参数列表",
                  "psPid": "115",
                  "psC": "",
                  "psA": "",
                  "psLevel": "2",
                  "path": null,
                  "children": []
                }
              ]
            }
          ]
        }
      ],
      "meta": {
        "msg": "删除成功",
        "status": 205
      }
    }
    

    1.6. 商品分类管理

    1.6.1. 商品分类数据列表

    • 请求路径:/cate/getByParam
    • 请求方法:post
    • 请求参数
    参数名参数说明备注
    type0/1/2值:0,1,2 分别表示显示一层二层三层分类列表
    【可选参数】如果不传递,则默认获取所有级别的分类
    pageNum当前页码值【可选参数】如果不传递,则默认获取所有分类
    pageSize每页显示多少条数据【可选参数】如果不传递,则默认获取所有分类
    • 响应参数
    参数名参数说明备注
    catId分类 ID
    catName分类名称
    catPid分类父 ID
    catLevel分类当前层级
    • 响应数据
    {
        "data": [
            {
                "cat_id": 1,
                "cat_name": "大家电",
                "cat_pid": 0,
                "cat_level": 0,
                "cat_deleted": false,
                "children": [
                    {
                        "cat_id": 3,
                        "cat_name": "电视",
                        "cat_pid": 1,
                        "cat_level": 1,
                        "cat_deleted": false,
                        "children": [
                            {
                                "cat_id": 6,
                                "cat_name": "曲面电视",
                                "cat_pid": 3,
                                "cat_level": 2,
                                "cat_deleted": false
                            },
                            {
                                "cat_id": 7,
                                "cat_name": "海信",
                                "cat_pid": 3,
                                "cat_level": 2,
                                "cat_deleted": false
                            }
                        ]
                    }
                ]
            }
        ],
        "meta": {
            "msg": "获取成功",
            "status": 200
        }
    }
    

    1.6.2. 添加分类

    • 请求路径:/cate/addCate
    • 请求方法:post
    • 请求参数
    参数名参数说明备注
    cat_pid分类父 ID不能为空,如果要添加1级分类,则父分类Id应该设置为 0
    cat_name分类名称不能为空
    cat_level分类层级不能为空,0表示一级分类;1表示二级分类;2表示三级分类
    • 响应数据
    {
      "data": {
        "catId": "8ca42342-baf4-4cfe-9beb-247d3767db45",
        "catName": "aa",
        "catPid": "1",
        "catLevel": 2,
        "catDeleted": 0,
        "catIcon": null,
        "catSrc": null
      },
      "meta": {
        "msg": "请求成功",
        "status": 201
      }
    }
    

    1.6.3. 根据 id 查询分类

    • 请求路径:/cate/getById
    • 请求方法:get
    • 请求参数
    参数名参数说明备注
    catId分类 ID不能为空携带在url中
    • 响应数据
    {
      "data": {
        "catId": "3",
        "catName": "电视",
        "catPid": "1",
        "catLevel": 1,
        "catDeleted": 0,
        "catIcon": "",
        "catSrc": ""
      },
      "meta": {
        "msg": "查询成功",
        "status": 207
      }
    }
    

    1.6.4. 编辑提交分类

    • 请求路径:/cate/updCate
    • 请求方法:post
    • 请求参数
    参数名参数说明备注
    catId分类 ID不能为空
    catName分类名称不能为空
    • 响应数据
    {
      "data": {
        "catId": "8ca42342-baf4-4cfe-9beb-247d3767db45",
        "catName": "测试",
        "catPid": "1",
        "catLevel": 2,
        "catDeleted": 0,
        "catIcon": null,
        "catSrc": null
      },
      "meta": {
        "msg": "修改成功",
        "status": 203
      }
    }
    

    1.6.5. 删除分类

    • 请求路径:/cate/delCate
    • 请求方法:get
    • 请求参数
    参数名参数说明备注
    catId分类 ID不能为空携带在url中
    • 响应数据
    {
      "data": null,
      "meta": {
        "msg": "删除成功",
        "status": 205
      }
    }
    

    1.7. 分类参数管理

    1.7.1. 参数列表

    • 请求路径:/attr/getAttrList
    • 请求方法:post
    • 请求参数
    参数名参数说明备注
    catId分类 ID不能为空
    attrSel[only,many]不能为空,通过 only 或 many 来获取分类静态参数还是动态参数
    • 响应参数
    参数名参数说明备注
    attrId分类参数 ID
    attrName分类参数名称
    catId分类参数所属分类
    attrSelonly:输入框(唯一) many:后台下拉列表/前台单选框
    attrWritemanual:手工录入 list:从列表选择
    attrVals如果 attr_write:list,那么有值,该值以逗号分隔
    • 响应数据
    {
      "data": {
        "total": 3802,
        "list": [
          {
            "attrId": "1",
            "attrName": "主观参数-型号",
            "catId": "1191",
            "attrSel": "only",
            "attrWrite": "manual",
            "deleteTime": null,
            "attrVals": "00002"
          }
    	}
      "meta": {
        "msg": "查询成功",
        "status": 207
      }
    }
    

    1.7.2. 添加动态参数或者静态属性

    • 请求路径:/attr/addAttr
    • 请求方法:post
    • 请求参数
    参数名参数说明备注
    catId分类 ID不能为空
    attrName参数名称不能为空
    attrSel[only,many]不能为空
    attrVals如果是 many 就需要填写值的选项,以逗号分隔【可选参数】
    • 响应数据
    {
      "data": {
        "attrId": "f4f44add-33f6-43ec-9929-226b91f8e4cb",
        "attrName": "主观参数-型号",
        "catId": "1191",
        "attrSel": "only",
        "attrWrite": "manual",
        "deleteTime": null,
        "attrVals": "00002"
      },
      "meta": {
        "msg": "创建成功",
        "status": 201
      }
    }
    

    1.7.3. 删除参数

    • 请求路径: /attr/delAttr
    • 请求方法:get
    • 请求参数
    参数名参数说明备注
    catId分类 ID不能为空携带在url中
    attrId参数 ID不能为空携带在url中
    • 响应数据
    {
        "data": null,
        "meta": {
            "msg": "删除成功",
            "status": 205
        }
    }
    

    1.7.4. 根据 ID 查询参数

    • 请求路径:/attr/findById
    • 请求方法:post
    • 请求参数
    参数名参数说明备注
    catId分类 ID不能为空
    attrId属性 ID不能为空
    attr_sel[only,many]不能为空
    attr_vals如果是 many 就需要填写值的选项,以逗号分隔
    • 响应数据
    {
      "data": {
        "attrId": "1",
        "attrName": "主观参数-型号",
        "catId": "1191",
        "attrSel": "only",
        "attrWrite": "manual",
        "deleteTime": null,
        "attrVals": "00002"
      },
      "meta": {
        "msg": "查询成功",
        "status": 207
      }
    }
    

    1.7.5. 编辑提交参数

    • 请求路径:/attr/updAttr
    • 请求方法:post
    • 请求参数
    参数名参数说明备注
    catId分类 ID不能为空,携带在请求体中`
    attrId属性 ID不能为空,携带在请求体中`
    attrName新属性的名字不能为空,携带在请求体
    attrSel属性的类型[many或only]不能为空,携带在请求体
    attrVals参数的属性值可选参数,携带在请求体
    • 响应数据
    {
      "data": {
        "attrId": "1",
        "attrName": "主观参数-型号1",
        "catId": "1191",
        "attrSel": "only",
        "attrWrite": "manual",
        "deleteTime": null,
        "attrVals": "00002"
      },
      "meta": {
        "msg": "修改成功",
        "status": 203
      }
    }
    

    版权声明:本文为CSDN博主「王志威-yc」的原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接及本声明。
    原文链接:https://blog.csdn.net/qq_20503733/article/details/105239905

Logo

前往低代码交流专区

更多推荐