后台接口文档示例

什么是接口文档？

在项目期间，先后端是分离开发的，为了先后有连贯性，就必须由先后开发工程师共同定义接口、写接口文档再根据接口文档去开发，一直到项目结束。

接口文档规范

• 方法

　　也就是咱们常写的新增，删除，修改，查询

• url

　　调用方法，通常是从前端调后端的方法地址

• 请求参数

　　通常分五列：字段、说明、类型、备注、是否必填 

• 返回参数

　　一、若是只返回接口调用成功仍是失败（新增、删除、修改等），则只有一个结构体：

　　　　　　code和message两个参数；

　　二、若是要返回某些参数，则有两个结构体：

　　　　　　是code/mesage/data；

　　　　　   是data里写返回的参数,data是object类型；

　　三、若是要返回列表，那么有三个结构体，

　　     　　 是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5个参数，其中list是Arrary类型，list里放object，object里是具体的参数。

了解目的

1. 用户登陆
2. 用户注册
3. 树形菜单
4. 文章查询
5. 文章新增
6. 文章修改
7. 文章删除

用户登陆：

　　接口调用and请求

http请求方式: POST （通常有两种get/post） https://xxx.xxx.xxx:8080/项目命名/vue/userAction_login.action

字段	说明	类型	是否必填
uname	名字	String	是
pwd	密码	String	是

登陆成功返回JSON数据包:

{ "msg":"登陆成功", "result":{ "uname":"用户名", "pwd":"密码" }, "code":1 }

用户或者密码为空返回JSON数据包:

{ "msg":"用户或者密码为空", "result":{ "uname":"用户名", "pwd":"密码" }, "code":0 }

用户或者密码错误返回JSON数据包:

{ "msg":"用户或者密码错误", "result":{ "uname":"用户名", "pwd":"密码" }, "code":0 }

参数	说明
msg	提示消息
result	返回登陆的用户名和密码
code	状态 0：登陆失败 1：登陆成功

用户注册

　　接口调用

https://xxx.xxx.xxx:8080/项目命名/vue/userAction_reg.action

字段	说明	类型	是否必填
uname	名字	String	是
pwd	密码	String	是

注册返回JSON数据包：

{
    "msg":"用户注册成功",
    "code":1
}

用户注册失败返回JSON数据包：

{
    "msg":"用户注册失败",
    "code":0
}

参数	说明
msg	提示消息
code	状态码 0：失败 1：成功

树形菜单

调用接口

https://xxx.xxx.xxx:8080/项目命名/vue/treeNodeAction.action

返回的json数据表以下：

{ "msg": "操做成功", "result": [ { "treeNodeId": 1, "treeNodeName": "系统管理", "treeNodeType": 1, "url": null, "position": 1, "icon": "el-icon-setting", "children": [ { "treeNodeId": 2, "treeNodeName": "用户管理", "treeNodeType": 2, "url": "/sys/VuexPage1", "position": 2, "icon": "el-icon-user", "children": [] }, { "treeNodeId": 3, "treeNodeName": "角色管理", "treeNodeType": 2, "url": "/sys/VuexPage2", "position": 3, "icon": "", "children": [] }, { "treeNodeId": 4, "treeNodeName": "密码修改", "treeNodeType": 2, "url": null, "position": 4, "icon": null, "children": [] } ] }, { "treeNodeId": 5, "treeNodeName": "论坛管理", "treeNodeType": 1, "url": null, "position": 5, "icon": "el-icon-reading", "children": [ { "treeNodeId": 6, "treeNodeName": "文章管理", "treeNodeType": 2, "url": "/sys/Articles", "position": 6, "icon": null, "children": [] } ] } ], "code": 1 }

参数	说明
msg	提示消息
result	返回树形菜单结果集
code	状态 0：失败 1：成功

Result树形菜单结果集

参数	说明
treeNodeId	菜单id
treeNodeName	菜单名
treeNodeType	菜单类型 1：父菜单2：跳转菜单
url	路由地址
icon	菜单图标
children	子菜单集，若是没有则为一个空json数组

文章查询

调用接口

https://xxx.xxx.xxx:8080/项目命名/vue/articleAction_list.action

参数	是否必填	说明
page	否	当前页码，默认为1
rows	否	一页展现多少条数据，默认为10
title	否	按文章标题查询

返回json数据包说明：

{ "result":[{"id":1,"title":"文章标题","body":"文章内容"], "pageBean":{ "page":1, "rows":10, "total":100, } }

result结果集

参数	说明
id	文章id
title	文章标题
body	文章内容

pageBean 分页对象说明

参数	说明
page	当前页码
rows	一页展现的条数
total	总条数

文章添加

调用接口

https://xxx.xxx.xxx:8080/项目命名/vue/articleAction_add.action

参数	是否必填	说明
title	是	文章标题
Body	否	文章内容

添加成功返回JSON数据包：

{"msg":"新增成功","result":[],"code":1}

添加失败返回JSON数据包：

{"msg":"新增失败","result":[],"code":0}

参数	说明
msg	提示消息
code	状态码 0：失败 1：成功

文章修改

调用接口

https://xxx.xxx.xxx:8080/项目命名/vue/articleAction_edit.action

参数	是否必须	说明
id	是	文章id
title	否	文章标题
body	否	文章内容

修改为功返回JSON数据包：

{"msg":"修改为功","code":1}

修改失败返回JSON数据包：

{"msg":"修改失败","code":0}

参数	说明
msg	提示消息
code	状态码 0：失败 1：成功

文章删除

调用接口

https://xxx.xxx.xxx:8080/项目命名/vue/articleAction_del.action

参数	是否必须	说明
id	是	文章id

删除成功返回JSON数据包：

{"msg":"删除成功","code":1}

删除失败返回JSON数据包：

{"msg":"删除失败","code":0}

参数	说明
msg	提示消息
code	状态码 0：失败 1：成功

 

 

谢谢观看！