前后端分离项目规范——接口文档示例

最新推荐文章于 2024-07-29 11:40:36 发布
最新推荐文章于 2024-07-29 11:40:36 发布
阅读量1.2k 收藏 17
点赞数 12
分类专栏： 技术博文 文章标签： 网络 java 服务器
CSDN_极客编程_毕设大师兄
本文链接：https://blog.csdn.net/weixin_53920044/article/details/140496933
版权

前后端分离项目中，要遵循一定的开发规范

一般有产品经理分析出需求，后端编写接口文档，然后前后端根据接口文档来并发开发项目。

以下为某系统接口文档示例 ：

公司人员系统接口文档-V1.0

1. 部门管理

1.1 部门列表查询

1.1.1 基本信息

请求路径：/depts

请求方式：GET

接口描述：该接口用于部门列表数据查询

1.1.2 请求参数

无

1.1.3 响应数据

参数格式：application/json

参数说明：

参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject[ ]非必须返回的数据
|- idnumber非必须id
|- namestring非必须部门名称
|- createTimestring非必须创建时间
|- updateTimestring非必须修改时间

响应数据样例：

{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "name": "学工部",
      "createTime": "2022-09-01T23:06:29",
      "updateTime": "2022-09-01T23:06:29"
    },
    {
      "id": 2,
      "name": "教研部",
      "createTime": "2022-09-01T23:06:29",
      "updateTime": "2022-09-01T23:06:29"
    }
  ]
}

1.2 删除部门

1.2.1 基本信息

请求路径：/depts/{id}

请求方式：DELETE

接口描述：该接口用于根据ID删除部门数据

1.2.2 请求参数

参数格式：路径参数

参数说明：

参数名类型是否必须备注
idnumber必须部门ID

请求参数样例：

/depts/1
1.2.3 响应数据

参数格式：application/json

参数说明：

参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject非必须返回的数据

响应数据样例：

{
    "code":1,
    "msg":"success",
    "data":null
}

1.3 添加部门

1.3.1 基本信息

请求路径：/depts

请求方式：POST

接口描述：该接口用于添加部门数据

1.3.2 请求参数

格式：application/json

参数说明：

参数名类型是否必须备注
namestring必须部门名称

请求参数样例：

{
	"name": "教研部"
}
1.3.3 响应数据

参数格式：application/json

参数说明：

参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject非必须返回的数据

响应数据样例：

{
    "code":1,
    "msg":"success",
    "data":null
}

1.4 根据ID查询

1.4.1 基本信息

请求路径：/depts/{id}

请求方式：GET

接口描述：该接口用于根据ID查询部门数据

1.4.2 请求参数

参数格式：路径参数

参数说明：

参数名类型是否必须备注
idnumber必须部门ID

请求参数样例：

/depts/1
1.4.3 响应数据

参数格式：application/json

参数说明：

参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject非必须返回的数据
|- idnumber非必须id
|- namestring非必须部门名称
|- createTimestring非必须创建时间
|- updateTimestring非必须修改时间

响应数据样例：

{
  "code": 1,
  "msg": "success",
  "data": {
    "id": 1,
    "name": "学工部",
    "createTime": "2022-09-01T23:06:29",
    "updateTime": "2022-09-01T23:06:29"
  }
}

1.5 修改部门

1.5.1 基本信息

请求路径：/depts

请求方式：PUT

接口描述：该接口用于修改部门数据

1.5.2 请求参数

格式：application/json

参数说明：

参数名类型是否必须备注
idnumber必须部门ID
namestring必须部门名称

请求参数样例：

{
	"id": 1,
	"name": "教研部"
}
1.5.3 响应数据

参数格式：application/json

参数说明：

参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject非必须返回的数据

响应数据样例：

{
    "code":1,
    "msg":"success",
    "data":null
}

2. 员工管理

2.1 员工列表查询

2.1.1 基本信息

请求路径：/emps

请求方式：GET

接口描述：该接口用于员工列表数据的条件分页查询

2.1.2 请求参数

参数格式：queryString

参数说明：

参数名称是否必须示例备注
name否张姓名
gender否1性别 , 1 男 , 2 女
begin否2010-01-01范围匹配的开始时间(入职日期)
end否2020-01-01范围匹配的结束时间(入职日期)
page是1分页查询的页码，如果未指定，默认为1
pageSize是10分页查询的每页记录数，如果未指定，默认为10

请求数据样例：

/emps?name=张&gender=1&begin=2007-09-01&end=2022-09-01&page=1&pageSize=10
2.1.3 响应数据

参数格式：application/json

参数说明：

名称类型是否必须默认值备注其他信息
codenumber必须响应码, 1 成功 , 0 失败
msgstring非必须提示信息
dataobject必须返回的数据
|- totalnumber必须总记录数
|- rowsobject []必须数据列表item 类型: object
|- idnumber非必须id
|- usernamestring非必须用户名
|- namestring非必须姓名
|- passwordstring非必须密码
|- entrydatestring非必须入职日期
|- gendernumber非必须性别 , 1 男 ; 2 女
|- imagestring非必须图像
|- jobnumber非必须职位, 说明: 1 班主任,2 讲师, 3 学工主管, 4 教研主管, 5 咨询师
|- deptIdnumber非必须部门id
|- createTimestring非必须创建时间
|- updateTimestring非必须更新时间

响应数据样例：

{
  "code": 1,
  "msg": "success",
  "data": {
    "total": 2,
    "rows": [
       {
        "id": 1,
        "username": "jinyong",
        "password": "123456",
        "name": "金庸",
        "gender": 1,
        "image": "https://web-framework.oss-cn-hangzhou.aliyuncs.com/2022-09-02-00-27-53B.jpg",
        "job": 2,
        "entrydate": "2015-01-01",
        "deptId": 2,
        "createTime": "2022-09-01T23:06:30",
        "updateTime": "2022-09-02T00:29:04"
      },
      {
        "id": 2,
        "username": "zhangwuji",
        "password": "123456",
        "name": "张无忌",
        "gender": 1,
        "image": "https://web-framework.oss-cn-hangzhou.aliyuncs.com/2022-09-02-00-27-53B.jpg",
        "job": 2,
        "entrydate": "2015-01-01",
        "deptId": 2,
        "createTime": "2022-09-01T23:06:30",
        "updateTime": "2022-09-02T00:29:04"
      }
    ]
  }
}

2.2 删除员工

2.2.1 基本信息

请求路径：/emps/{ids}

请求方式：DELETE

接口描述：该接口用于批量删除员工的数据信息

2.2.2 请求参数

参数格式：路径参数

参数说明：

参数名类型示例是否必须备注
ids数组 array1,2,3必须员工的id数组

请求参数样例：

/emps/1,2,3
2.2.3 响应数据

参数格式：application/json

参数说明：

参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject非必须返回的数据

响应数据样例：

{
    "code":1,
    "msg":"success",
    "data":null
}

2.3 添加员工

2.3.1 基本信息

请求路径：/emps

请求方式：POST

接口描述：该接口用于添加员工的信息

2.3.2 请求参数

参数格式：application/json

参数说明：

名称类型是否必须备注
usernamestring必须用户名
namestring必须姓名
gendernumber必须性别, 说明: 1 男, 2 女
imagestring非必须图像
deptIdnumber非必须部门id
entrydatestring非必须入职日期
jobnumber非必须职位, 说明: 1 班主任,2 讲师, 3 学工主管, 4 教研主管, 5 咨询师

请求数据样例：

{
  "image": "https://web-framework.oss-cn-hangzhou.aliyuncs.com/2022-09-03-07-37-38222.jpg",
  "username": "linpingzhi",
  "name": "林平之",
  "gender": 1,
  "job": 1,
  "entrydate": "2022-09-18",
  "deptId": 1
}
2.3.3 响应数据

参数格式：application/json

参数说明：

参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject非必须返回的数据

响应数据样例：

{
    "code":1,
    "msg":"success",
    "data":null
}

2.4 根据ID查询

2.4.1 基本信息

请求路径：/emps/{id}

请求方式：GET

接口描述：该接口用于根据主键ID查询员工的信息

2.4.2 请求参数

参数格式：路径参数

参数说明：

参数名类型是否必须备注
idnumber必须部门ID

请求参数样例：

/emps/1
2.4.3 响应数据

参数格式：application/json

参数说明：

名称类型是否必须默认值备注其他信息
codenumber必须响应码, 1 成功 , 0 失败
msgstring非必须提示信息
dataobject必须返回的数据
|- idnumber非必须id
|- usernamestring非必须用户名
|- namestring非必须姓名
|- passwordstring非必须密码
|- entrydatestring非必须入职日期
|- gendernumber非必须性别 , 1 男 ; 2 女
|- imagestring非必须图像
|- jobnumber非必须职位, 说明: 1 班主任,2 讲师, 3 学工主管, 4 教研主管, 5 咨询师
|- deptIdnumber非必须部门id
|- createTimestring非必须创建时间
|- updateTimestring非必须更新时间

响应数据样例：

{
  "code": 1,
  "msg": "success",
  "data": {
    "id": 2,
    "username": "zhangwuji",
    "password": "123456",
    "name": "张无忌",
    "gender": 1,
    "image": "https://web-framework.oss-cn-hangzhou.aliyuncs.com/2022-09-02-00-27-53B.jpg",
    "job": 2,
    "entrydate": "2015-01-01",
    "deptId": 2,
    "createTime": "2022-09-01T23:06:30",
    "updateTime": "2022-09-02T00:29:04"
  }
}

2.5 修改员工

2.5.1 基本信息

请求路径：/emps

请求方式：PUT

接口描述：该接口用于修改员工的数据信息

2.5.2 请求参数

参数格式：application/json

参数说明：

名称类型是否必须备注
idnumber必须id
usernamestring必须用户名
namestring必须姓名
gendernumber必须性别, 说明: 1 男, 2 女
imagestring非必须图像
deptIdnumber非必须部门id
entrydatestring非必须入职日期
jobnumber非必须职位, 说明: 1 班主任,2 讲师, 3 学工主管, 4 教研主管, 5 咨询师

请求数据样例：

{
  "id": 1,
  "image": "https://web-framework.oss-cn-hangzhou.aliyuncs.com/2022-09-03-07-37-38222.jpg",
  "username": "linpingzhi",
  "name": "林平之",
  "gender": 1,
  "job": 1,
  "entrydate": "2022-09-18",
  "deptId": 1
}
2.5.3 响应数据

参数格式：application/json

参数说明：

参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject非必须返回的数据

响应数据样例：

{
    "code":1,
    "msg":"success",
    "data":null
}

2.6 文件上传

2.6.1 基本信息

请求路径：/upload

请求方式：POST

接口描述：上传图片接口

2.6.2 请求参数

参数格式：multipart/form-data

参数说明：

参数名称参数类型是否必须示例备注
imagefile是
2.6.3 响应数据

参数格式：application/json

参数说明：

参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject非必须返回的数据，上传图片的访问路径

响应数据样例：

{
    "code": 1,
    "msg": "success",
    "data": "https://web-framework.oss-cn-hangzhou.aliyuncs.com/2022-09-02-00-27-0400.jpg"
}

3. 其他接口

3.1 登录

3.1.1 基本信息

请求路径：/login

请求方式：POST

接口描述：该接口用于员工登录Tlias智能学习辅助系统，登录完毕后，系统下发JWT令牌。

3.1.2 请求参数

参数格式：application/json

参数说明：

名称类型是否必须备注
usernamestring必须用户名
passwordstring必须密码

请求数据样例：

{
	"username": "jinyong",
    "password": "123456"
}
3.1.3 响应数据

参数格式：application/json

参数说明：

名称类型是否必须默认值备注其他信息
codenumber必须响应码, 1 成功 ; 0 失败
msgstring非必须提示信息
datastring必须返回的数据 , jwt令牌

响应数据样例：

{
  "code": 1,
  "msg": "success",
  "data": "eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoi6YeR5bq4IiwiaWQiOjEsInVzZXJuYW1lIjoiamlueW9uZyIsImV4cCI6MTY2MjIwNzA0OH0.KkUc_CXJZJ8Dd063eImx4H9Ojfrr6XMJ-yVzaWCVZCo"
}
3.1.4 备注说明

用户登录成功后，系统会自动下发JWT令牌，然后在后续的每次请求中，都需要在请求头header中携带到服务端，请求头的名称为 token ，值为 登录时下发的JWT令牌。

如果检测到用户未登录，则会返回如下固定错误信息：

{
	"code": 0,
	"msg": "NOT_LOGIN",
	"data": null
}

​

大熊计算机毕设(极客编程)
关注
专栏目录
接口文档(范例).doc
12-19
接口详细设计文档，包含：编写目的，名词解释，组件分布图，程序结构，接入处理线程类图，接收线程类图，启动控制图，程序设计说明，对原系统的改动，类图，时序图，流程图等。
后端接口文档例子 word
03-18
word版接口文档
花10分钟写个漂亮的后端API接口模板！
最新发布
田维常
07-29 547
你好，我是田哥在这微服务架构盛行的黄金时段，加上越来越多的前后端分离，导致后端API接口规范变得越来越重要了。比如：统一返回参数形式、统一返回码、统一异常处理、集成swagger等。目的主要是规范后端项目代码，以及便于前端沟通联通以及问题的排查。本文内容：统一返回参数形式目前主流的返回参数形式：{ "code":200000, "message":"成功", "data":{ ...
接口文档编写规范(前后端分离项目接口api)
伟庭的博客
09-23 7466
接口文档编写规范(前后端分离项目接口api)
常用接口文档模板(markdown版)
zhamors
10-11 1490
【代码】常用接口文档模板(markdown版)
全网最全的接口文档速成
weixin_69912448的博客
07-10 1472
当前项目中，前端代码和后端代码混合在一起，是存在问题的，存在什么问题呢？主要存在以下几点问题：1). 开发人员同时负责前端和后端代码开发，分工不明确2). 开发效率低3). 前后端代码混合在一个工程中，不便于管理4). 对开发人员要求高(既会前端，又会后端)，人员招聘困难为了解决上述提到的问题，现在比较主流的开发方式，就是前后端分离开发，前端人员开发前端的代码，后端开发人员开发服务端的业务功能，分工明确，各司其职。我们本章节，就是需要将之前的项目进行优化改造，变成前后端分离开发的项目。
接口文档实例
01-10
对接口文档的描述. 甲方节点和乙方节点的同意.
「接口文档」示例详解
热门推荐
weixin_42862555的博客
02-26 3万+
文档示例 用户登录注册 登录 注册 树形菜单 增删查改 查 增 删 改 用户登录注册 登录 http请求方式: POST（请使用https协议） https://localhost:8080/hu/vue/userAction_login.action 参数 是否必须 说明 uname 是 用户名 upwd 是
接口文档-示例
yirenyuan的博客
02-29 1848
参数格式：application/json。接口描述：该接口用于根据ID查询员工信息。
Java「接口文档」示例
weixin_42862555的博客
02-26 1万+
接口概念 官方解释：Java接口是一系列方法的声明，是一些方法特征的集合，一个接口只有方法的特征没有方法的实现，因此这些方法可以在不同的地方被不同的类实现，而这些实现可以具有不同的行为（功能）。 我的解释：接口可以理解为一种特殊的类，里面全部是由全局常量和公共的抽象方法所组成。接口是解决Java无法使用多继承的一种手段，但是接口在实际中更多的作用是制定标准的。或者我们可以直接把接口理解为100%的抽象类，既接口中的方法必须全部是抽象方法。（JDK1.8之前可以这样理解） 接口的特点 就像一个类一样，一个接口
接口文档示例.docx
08-13
开发文档模版，便于后台技术开发人员与前端开发人员的交流
restful前后端分离api接口文档模板
09-20
restful前后端分离api接口文档模板,javaweb开发接口文档
前后端开发接口文档
03-15
课程提供了前后端开发接口文档（采用 Swagger 语言进行编写），并与 Nginx 进行了整 合。双击 Nginx 执行文件启动后，在地址栏输入 http://localhost:801 即可访问 API 文档
开放接口文档案例
11-06
接口文档实例,移动端,PC端接口自定义案例
前后端分离时代的API文档——Swagger
m0_66884848的博客
04-02 998
你应该知道如今的互联网时代。随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要。 一、OpenApi介绍 OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTfu...
如何维护接口文档供外部调用——在线接口文档管理
09-22 1125
上个章节初步将一个应用运行起来，由于服务不会单独存在，服务开发团队必然与其他服务团队进行服务调用，暴露出对外接口势在必行。早期做开发的时候，大家习惯于以 word 或 excel 的形式，但弊端显而易见，一旦接口发生变动，文档需要同步更新，遗憾的是很多接口已经更新，但文档都没有跟上，相信你也有过痛苦的经历。本文带领你认识几款接口文档管理工具，并实现本案例实践中用到的在线接口文档管理。 几款 API...
接口文档——Swagger
qq_53226437的博客
03-07 8086
Swagger 接口文档对于前后端开发人员都十分重要。尤其近几年流行前后 端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项 目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接 口文档和实际情况不一致 很多人员会抱怨别人写的接口文档不规范，不及时更新。当时当 自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心 如果接口文档可以实时动态生成就不会出现上面问题 Swagger 可以完美的解决上面的问题 Open API Open API 规范(OpenAPI Specific
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

大熊计算机毕设(极客编程)

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值