excel能翻译中文吗
620
2023-01-09
接口文档在线（接口文档和接口）
本篇文章给大家谈谈接口文档在线，以及接口文档和接口对应的知识点，希望对各位有所帮助，不要忘了收藏本站喔。
今天给各位分享接口文档在线的知识，其中也会对接口文档和接口进行解释，如果能碰巧解决你现在面临的问题，别忘了关注本站，现在开始吧！
*以下是入库，修改，出库，查询，领取操作，上传文件，扫面快件，后台手工操作等等系统所需要接口，
接口时区，时间格式后台服务器统一处理，前端只做展示，不处理，后台优化。
接口在线测试地址为swagger-ui.html,
测试test文件上传页面地址upload.html
文字识别接口ocr/scan?url=group1/M00/00/00/rBAzTFtAt7WADBSLAAEeePITqg8669.jpg
可换成其他图片地址
快递后台管理系统地址login
快件扫描 ——》job【暂时8s执行一次【1小时执行完毕450个峰值 1*60*7.5】即可查询扫描结果】
所写字段注释
`id` int(11) NOT NULL AUTO_INCREMENT COMMENT 'ID',
`account` varchar(255) DEFAULT NULL COMMENT '所属设备账户',
`number` varchar(50) DEFAULT NULL COMMENT '运单号',
`phone` varchar(11) DEFAULT NULL COMMENT '手机号',
`code` varchar(20) DEFAULT NULL COMMENT '取货码',
`img_url` varchar(255) DEFAULT NULL COMMENT '图片url',
`success_date` datetime DEFAULT NULL COMMENT '领取时间',
`status` varchar(255) DEFAULT NULL COMMENT '领取状态，scanning（待识别）,wait（入库待领取）,success（领取）,fail（识别失败）',
`remark` varchar(255) DEFAULT NULL,
`create_date` datetime DEFAULT NULL,
`update_date` datetime DEFAULT NULL,
1
2
3
4
5
6
7
8
9
10
11
12
1.入库保存快件
packUp/insert
请求体post
{
"account": "001",<SaaS账户码，必填
"imgUrl": "group1/M00/00/00/rBAzTFst2PmAFYHoAAE2VbemYe8895.jpg",
"number": "a123456",
"remark": "备注"<非必填
}
1
2
3
4
5
6
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": 1
}
1
2
3
4
5
6
7
2.根据快点单号查询
get请求 packUp/get4number?number=b13131321
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": {
"id": 6,
"account": "扫描枪1号",
"number": "b13131321",
"phone": "14758265423",
"code": "0123",
"imgUrl": null,
"successDate": null,
"status": "wait",
"remark": "备注",
"createDate": null,
"updateDate": null
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
3.分页查询 支持模糊查询，支持查询总记录数
packUp/list
请求体post
{
"pageNo":"1",
"pageSize":"10",
"id":10, <条件查询非必填
"account":"003", <SaaS账户码，必填
"number":"abc123456", <条件查询非必填，支持模糊查询
"phone":"15638458525", <条件查询非必填，支持模糊查询
"code":"1234", <条件查询非必填，支持模糊查询
"imgUrl":"group1/M00/00/00/rBAzTFtFqi-AV8qNAAgr7tOdRhg298.jpg", <条件查询非必填
"status":"success" <条件查询非必填
"startCreateDate":"2018-08-10 13:42:45" <开始入库时间，非必填
"endCreateDate":"2018-08-10 13:42:45" <结束入库时间，非必填
}
1
2
3
4
5
6
7
8
9
10
11
12
13
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": {
"total": 67,
"rows": [
{
"id": "1826",
"account": null,
"number": "3866940607293",
"phone": "17760746217",
"code": "5-5-5003",
"imgUrl": "http://image.31xiaoyuan.com:80/group1/M00/00/07/rBAzTlttJdSAFHLSAASq5DS_AEs492.jpg",
"successDate": null,
"status": "wait",
"remark": "已发送短信",
"createDate": "2018-08-10 13:42:45",
"updateDate": "2018-08-10 15:42:51"
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
4 .领取操作 后台自动更新remark 为已领取
POST 请求 packUp/receiveStatus?number=a123456789
响应体
{
"message": {
"code": "212",
"msg": "快递已领取，不可重复领取"
},
"data": null
}
1
2
3
4
5
6
7
5.删除快件
get请求 packUp/remove?packupID=11 #packupID 此条记录ID
响应体
{
"message": {
"code": "200",
"msg": "删除成功"
},
"data": 0
}
1
2
3
4
5
6
7
6.上传文件
post请求 upload/uploadFile
响应体
{
"message":{
"code":"200",
"msg":"获取成功"
},
"data":"group1/M00/00/00/rBAzTFst89WAU3TkAAAQBiAihO4765.jpg"
}
1
2
3
4
5
6
7
5.查看文件
get请求 upload/query4url?url=group1/M00/00/00/rBAzTFst89WAU3TkAAAQBiAihO4765.jpg
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": "120.27.209.6:8888/group1/M00/00/00/rBAzTFst89WAU3TkAAAQBiAihO4765.jpg"
}
1
2
3
4
5
6
7
6.修改快件-入库修改
packUp/update
post请求体
{
"id": "8",
"account": "00000",<SaaS账户码，必填
"code": "1111",<非必填，有值即修改
"imgUrl": "group1/M00/00/00/rBAzTFtFqi-AV8qNAAgr7tOdRhg298.jpg",<非必填，有值即修改
"status": "scanning",<非必填，有值即修改
"remark": "修改图片"<非必填，有值即修改
}
1
2
3
4
5
6
7
8
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": 0
}
1
2
3
4
5
6
7
7. 登录入口传参数–也可参考swagger
app/user/login
post请求体
{
"password": "123456",《密码》
"username": "18337151123"《手机号》
}
1
2
3
4
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": {
"deptId": "1", 《SaaS账户码》
"userId": "140"《用户ID，现在简单做，没有token等，后期加入》
}
}
1
2
3
4
5
6
7
8
9
10
8. 注册接口传参数–也可参考swagger
app/user/register
post请求体
{
"deptId": 1,《SaaS账户码，由后台管理开户审核》
"password": "123456",《登录密码》
"username": "18337157111"《注册登录账户》
}
1
2
3
4
5
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": {}
}
1
2
3
4
5
6
7
接下来要有当前文档的版本修订信息，即为历史修订信息，应当包含基础的信息有：版本号、修订日期、修订人、修订说明等。
开始编写文档的目录结构，注意大标题和小标题的使用，需要合理的运用说明。首先当然是文档的说明信息，再来是一些准备信息和流程信息，然后开始接口说明，最后可以有举例、常见问题、注意事项、响应码的说明信息等等。
下面开始按照文档的目录结构逐一进行详细的介绍说明，比如文档说明的介绍，用高效简洁的语言明确的说明文档信息，注意文档中大标题应当字体大小样式一致，小标题也应当字体大小注意保持一致。
简单的说明技术资料获取及准备，确认调用系统信息比较重要，需要确认编码格式，防止乱码，确认当前的文档版本是否是要使用的版本，否则白做无用功，项目的搭建环境简单说明即可。
开始说明接口的调用流程，如何调用接口，需要做的一些准备，说明引入相应的依赖以及配置需要配置的文件。
现在可以开始接口的说明，接口的说明信息应当包含接口的名称，接口的地址，接口的协议，然后针对当前接口下的方法说明。
方法的说明应当包含方法的描述，即其作用，方法的请求参数说明，以及响应的参数说明，参数说明应当包含参数的类型，参数名称，参数的含义，并且备注参数是否必须传递。
9
接口说明完之后，就是文档的末尾，有注意事项添加一些注意事项，或者附录说明，添加标注。
当下常用的是RestFul风格的定义规范， 之前开发是清一色Get、Post。引入RestFul后感觉接口定义规范很多，看接口地址就知晓是什么功能， 一起来看看列的一些基础规范吧。
API与客户端用户的通信协议，总是使用HTTPS协议，以确保交互数据的传输安全。
应该尽量将API部署在专用域名之下接口文档在线： https://api.example.com
如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下： https://www.example.com/api
https://api.example.com/v{n}
1、应该将API的版本号放入URL。
2、采用多版本并存，增量发布的方式。
3、n代表版本号，分为整型和浮点型
整型： 大功能版本， 如v1、v2、v3 ...
浮点型： 补充功能版本， 如v1.1、v1.2、v2.1、v2.2 ...
4、对于一个 API 或服务，应在生产中最多保留 3 个最详细的版本
路径又称"终点"（end point），表示API的具体网址。
1、在RESTful架构中，每个网址代表一种资源(resource),所以网址中不能有动词，只能有名词。
【所用的名词往往与数据库的表格名对应】
2、数据库中的表一般都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。
例子: https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees
GET（SELECT）： 从服务器取出资源（一项或多项）。
POST（CREATE）： 在服务器新建一个资源。
PUT（UPDATE）： 在服务器更新资源（客户端提供改变后的完整资源）。
DELETE（DELETE）： 从服务器删除资源。
例子：
GET /v1/products 获取所有商品
GET /v1/products/ID 获取某个指定商品的信息
POST /v1/products 新建一个商品
PUT /v1/products/ID 更新某个指定商品的信息
DELETE /v1/products/ID 删除某个商品,更合理的设计详见【9、非RESTful API的需求】
GET /v1/products/ID/purchases 列出某个指定商品的所有投资者
GET /v1/products/ID/purchases/ID 获取某个指定商品的指定投资者信息
若记录数量很多，服务器不可能返回全部记录给用户。
API应该提供分页参数及其它筛选参数，过滤返回结果。
/v1/products?page=1pageSize=20 指定第几页，以及每页的记录数。
/v1/products?sortBy=nameℴ=asc 指定返回结果按照哪个属性排序，以及排序顺序。
传入参数分为4种类型：
1、cookie： 一般用于OAuth认证
2、request header： 一般用于OAuth认证
3、请求body数据：
4、地址栏参数：
1）restful 地址栏参数 /v1/products/ID ID为产品编号，获取产品编号为ID的信息
2）get方式的查询字段 见【六、过滤信息】
response：
----------------------------------------
{
status: 200, // 详见【status】
data: {
code: 1, // 详见【code】
data: {} || [], // 数据
message: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】
sysMessage: 'success' // 存放响应信息提示,调试使用,中英文都行
... // 其它参数，如 total【总记录数】等
},
msg: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】
sysMsg: 'success' // 存放响应信息提示,调试使用,中英文都行
}
----------------------------------------
【status】:
200: OK 400: Bad Request 500：Internal Server Error
401：Unauthorized
403：Forbidden
404：Not Found
【code】:
1: 获取数据成功 | 操作成功 0：获取数据失败 | 操作失败
1、实际业务开展过程中，可能会出现各种的api不是简单的restful 规范能实现的。
2、需要有一些api突破restful规范原则。
3、特别是移动互联网的api设计，更需要有一些特定的api来优化数据请求的交互。
1)、删除单个 | 批量删除 ： DELETE /v1/product body参数{ids：[]}
2)、页面级API : 把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据
1、前端需要哪些字段，API接口应该返回哪些字段，字段不多也不少。
2、更新功能尽量做到：初次返回的原始数据参数与提交更新的数据参数结构一致。
3、时间参数，尽量以一致格式的字符串传递， 如：
‘2019-01’ | ‘2019/01’
‘2019-01-01’ | ‘2019/01/01’
‘2019-01-01 12:12:12’ | ‘2019/01/01 12:12:12’
1、尽量采用自动化接口文档，可以做到在线测试，同步更新。
2、应包含：接口BASE地址、接口版本、接口模块分类等。
3、每个接口应包含：
接口地址：不包含接口BASE地址。
请求方式: get、post、put、delete等。
请求参数：数据格式【默认JSON、可选form data】、数据类型、是否必填、中文描述。
相应参数：类型、中文描述。
接口函数一旦发布就不能改了，要保持兼容性，拼写错误也不能改了，所以要仔细检查拼写，否则会被同行嘲笑很多年。
著名悲剧：unix 的 creat
2. 不仅是英文单词不要拼错，时态也不要错。
比如：
返回bool的判断函数，单数要用 is 复数要用are，这样你的命名就和文档中的描述保持了一致性。
表示状态的变量或者函数要注意时态，比如 onXxxxChanged 表示xxx已经变化了，isConnecting表示正在连接。
正确的时态可以给使用者传递更丰富的信息。
3. 函数最好是动宾结构
动宾结构就是 doSomething，这样的函数命名含义明确
比如： openFile, allocBuffer, setName
如果这个函数的动词宾语就是这个对象本身，那么可以省略掉宾语
4. 属性命名最好是定语+名词
比如 fileName, maxSize, textColor
5. 不要用生僻单词，这不是秀英语的地方，也不要用汉语拼音
比如：rendezvous，估计大多数人要去查词典才知道什么意思，这个词源自法语，是约会的意思。
Symbian OS里有个用它命名的函数，开发Symbian的是英国人，也许人家觉得很平常吧，反正我是查了词典才知道的。
6. 不要自己发明缩写
除非是约定俗成已经被广泛使用的缩写，否则老老实实用完整拼写。
坏例子: count-cnt, manager-mngr password-pw button-btn
现代的IDE都有很好的自动完成功能，名字长一点没关系的，可读性更重要。
7. 保持方法的对称性，有些方法一旦出现就应该是成对的，
比如 有open就要有close，有alloc就要有free，有add就要有remove，这些单词基本是固定搭配的，使用者就很容易理解。
如果 open对应clear就有点让人困惑了。 关于接口文档在线和接口文档和接口的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 接口文档在线的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于接口文档和接口、接口文档在线的信息别忘了在本站进行查找喔。
本文目录一览：
接口对接说明文档
接口对接说明文档*以下是入库，修改，出库，查询，领取操作，上传文件，扫面快件，后台手工操作等等系统所需要接口，
接口时区，时间格式后台服务器统一处理，前端只做展示，不处理，后台优化。
接口在线测试地址为swagger-ui.html,
测试test文件上传页面地址upload.html
文字识别接口ocr/scan?url=group1/M00/00/00/rBAzTFtAt7WADBSLAAEeePITqg8669.jpg
可换成其他图片地址
快递后台管理系统地址login
快件扫描 ——》job【暂时8s执行一次【1小时执行完毕450个峰值 1*60*7.5】即可查询扫描结果】
所写字段注释
`id` int(11) NOT NULL AUTO_INCREMENT COMMENT 'ID',
`account` varchar(255) DEFAULT NULL COMMENT '所属设备账户',
`number` varchar(50) DEFAULT NULL COMMENT '运单号',
`phone` varchar(11) DEFAULT NULL COMMENT '手机号',
`code` varchar(20) DEFAULT NULL COMMENT '取货码',
`img_url` varchar(255) DEFAULT NULL COMMENT '图片url',
`success_date` datetime DEFAULT NULL COMMENT '领取时间',
`status` varchar(255) DEFAULT NULL COMMENT '领取状态，scanning（待识别）,wait（入库待领取）,success（领取）,fail（识别失败）',
`remark` varchar(255) DEFAULT NULL,
`create_date` datetime DEFAULT NULL,
`update_date` datetime DEFAULT NULL,
1
2
3
4
5
6
7
8
9
10
11
12
1.入库保存快件
packUp/insert
请求体post
{
"account": "001",<SaaS账户码，必填
"imgUrl": "group1/M00/00/00/rBAzTFst2PmAFYHoAAE2VbemYe8895.jpg",
"number": "a123456",
"remark": "备注"<非必填
}
1
2
3
4
5
6
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": 1
}
1
2
3
4
5
6
7
2.根据快点单号查询
get请求 packUp/get4number?number=b13131321
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": {
"id": 6,
"account": "扫描枪1号",
"number": "b13131321",
"phone": "14758265423",
"code": "0123",
"imgUrl": null,
"successDate": null,
"status": "wait",
"remark": "备注",
"createDate": null,
"updateDate": null
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
3.分页查询 支持模糊查询，支持查询总记录数
packUp/list
请求体post
{
"pageNo":"1",
"pageSize":"10",
"id":10, <条件查询非必填
"account":"003", <SaaS账户码，必填
"number":"abc123456", <条件查询非必填，支持模糊查询
"phone":"15638458525", <条件查询非必填，支持模糊查询
"code":"1234", <条件查询非必填，支持模糊查询
"imgUrl":"group1/M00/00/00/rBAzTFtFqi-AV8qNAAgr7tOdRhg298.jpg", <条件查询非必填
"status":"success" <条件查询非必填
"startCreateDate":"2018-08-10 13:42:45" <开始入库时间，非必填
"endCreateDate":"2018-08-10 13:42:45" <结束入库时间，非必填
}
1
2
3
4
5
6
7
8
9
10
11
12
13
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": {
"total": 67,
"rows": [
{
"id": "1826",
"account": null,
"number": "3866940607293",
"phone": "17760746217",
"code": "5-5-5003",
"imgUrl": "http://image.31xiaoyuan.com:80/group1/M00/00/07/rBAzTlttJdSAFHLSAASq5DS_AEs492.jpg",
"successDate": null,
"status": "wait",
"remark": "已发送短信",
"createDate": "2018-08-10 13:42:45",
"updateDate": "2018-08-10 15:42:51"
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
4 .领取操作 后台自动更新remark 为已领取
POST 请求 packUp/receiveStatus?number=a123456789
响应体
{
"message": {
"code": "212",
"msg": "快递已领取，不可重复领取"
},
"data": null
}
1
2
3
4
5
6
7
5.删除快件
get请求 packUp/remove?packupID=11 #packupID 此条记录ID
响应体
{
"message": {
"code": "200",
"msg": "删除成功"
},
"data": 0
}
1
2
3
4
5
6
7
6.上传文件
post请求 upload/uploadFile
响应体
{
"message":{
"code":"200",
"msg":"获取成功"
},
"data":"group1/M00/00/00/rBAzTFst89WAU3TkAAAQBiAihO4765.jpg"
}
1
2
3
4
5
6
7
5.查看文件
get请求 upload/query4url?url=group1/M00/00/00/rBAzTFst89WAU3TkAAAQBiAihO4765.jpg
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": "120.27.209.6:8888/group1/M00/00/00/rBAzTFst89WAU3TkAAAQBiAihO4765.jpg"
}
1
2
3
4
5
6
7
6.修改快件-入库修改
packUp/update
post请求体
{
"id": "8",
"account": "00000",<SaaS账户码，必填
"code": "1111",<非必填，有值即修改
"imgUrl": "group1/M00/00/00/rBAzTFtFqi-AV8qNAAgr7tOdRhg298.jpg",<非必填，有值即修改
"status": "scanning",<非必填，有值即修改
"remark": "修改图片"<非必填，有值即修改
}
1
2
3
4
5
6
7
8
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": 0
}
1
2
3
4
5
6
7
7. 登录入口传参数–也可参考swagger
app/user/login
post请求体
{
"password": "123456",《密码》
"username": "18337151123"《手机号》
}
1
2
3
4
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": {
"deptId": "1", 《SaaS账户码》
"userId": "140"《用户ID，现在简单做，没有token等，后期加入》
}
}
1
2
3
4
5
6
7
8
9
10
8. 注册接口传参数–也可参考swagger
app/user/register
post请求体
{
"deptId": 1,《SaaS账户码，由后台管理开户审核》
"password": "123456",《登录密码》
"username": "18337157111"《注册登录账户》
}
1
2
3
4
5
响应体
{
"message": {
"code": "200",
"msg": "获取成功"
},
"data": {}
}
1
2
3
4
5
6
7
什么是接口文档，如何写接口，有什么规范
首先要有一个文档的标题，XXX接口文档，符合当前文档的说明，文档的生产日期，以及公司名称等。现在开始写一个dubbo接口文档，定义标题，以及日期，这里公司省略。使用confluence在线编辑，Confluence为团队提供一个协作环境。团队成员协同地编写文档和管理项目。从此打破不同团队、不同部门以及个人之间信息孤岛的僵局，Confluence实现了资源的共享。接下来要有当前文档的版本修订信息，即为历史修订信息，应当包含基础的信息有：版本号、修订日期、修订人、修订说明等。
开始编写文档的目录结构，注意大标题和小标题的使用，需要合理的运用说明。首先当然是文档的说明信息，再来是一些准备信息和流程信息，然后开始接口说明，最后可以有举例、常见问题、注意事项、响应码的说明信息等等。
下面开始按照文档的目录结构逐一进行详细的介绍说明，比如文档说明的介绍，用高效简洁的语言明确的说明文档信息，注意文档中大标题应当字体大小样式一致，小标题也应当字体大小注意保持一致。
简单的说明技术资料获取及准备，确认调用系统信息比较重要，需要确认编码格式，防止乱码，确认当前的文档版本是否是要使用的版本，否则白做无用功，项目的搭建环境简单说明即可。
开始说明接口的调用流程，如何调用接口，需要做的一些准备，说明引入相应的依赖以及配置需要配置的文件。
现在可以开始接口的说明，接口的说明信息应当包含接口的名称，接口的地址，接口的协议，然后针对当前接口下的方法说明。
方法的说明应当包含方法的描述，即其作用，方法的请求参数说明，以及响应的参数说明，参数说明应当包含参数的类型，参数名称，参数的含义，并且备注参数是否必须传递。
9
接口说明完之后，就是文档的末尾，有注意事项添加一些注意事项，或者附录说明，添加标注。
Restful接口文档规范
基于目前接口文档在线的大前端时代，对于常年负责后台开发接口文档在线的接口文档在线我来说， 最重要的就是提供稳定的接口和文档。便于小伙伴们进行业务对接。当下常用的是RestFul风格的定义规范， 之前开发是清一色Get、Post。引入RestFul后感觉接口定义规范很多，看接口地址就知晓是什么功能， 一起来看看列的一些基础规范吧。
API与客户端用户的通信协议，总是使用HTTPS协议，以确保交互数据的传输安全。
应该尽量将API部署在专用域名之下接口文档在线： https://api.example.com
如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下： https://www.example.com/api
https://api.example.com/v{n}
1、应该将API的版本号放入URL。
2、采用多版本并存，增量发布的方式。
3、n代表版本号，分为整型和浮点型
整型： 大功能版本， 如v1、v2、v3 ...
浮点型： 补充功能版本， 如v1.1、v1.2、v2.1、v2.2 ...
4、对于一个 API 或服务，应在生产中最多保留 3 个最详细的版本
路径又称"终点"（end point），表示API的具体网址。
1、在RESTful架构中，每个网址代表一种资源(resource),所以网址中不能有动词，只能有名词。
【所用的名词往往与数据库的表格名对应】
2、数据库中的表一般都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。
例子: https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees
GET（SELECT）： 从服务器取出资源（一项或多项）。
POST（CREATE）： 在服务器新建一个资源。
PUT（UPDATE）： 在服务器更新资源（客户端提供改变后的完整资源）。
DELETE（DELETE）： 从服务器删除资源。
例子：
GET /v1/products 获取所有商品
GET /v1/products/ID 获取某个指定商品的信息
POST /v1/products 新建一个商品
PUT /v1/products/ID 更新某个指定商品的信息
DELETE /v1/products/ID 删除某个商品,更合理的设计详见【9、非RESTful API的需求】
GET /v1/products/ID/purchases 列出某个指定商品的所有投资者
GET /v1/products/ID/purchases/ID 获取某个指定商品的指定投资者信息
若记录数量很多，服务器不可能返回全部记录给用户。
API应该提供分页参数及其它筛选参数，过滤返回结果。
/v1/products?page=1pageSize=20 指定第几页，以及每页的记录数。
/v1/products?sortBy=nameℴ=asc 指定返回结果按照哪个属性排序，以及排序顺序。
传入参数分为4种类型：
1、cookie： 一般用于OAuth认证
2、request header： 一般用于OAuth认证
3、请求body数据：
4、地址栏参数：
1）restful 地址栏参数 /v1/products/ID ID为产品编号，获取产品编号为ID的信息
2）get方式的查询字段 见【六、过滤信息】
response：
----------------------------------------
{
status: 200, // 详见【status】
data: {
code: 1, // 详见【code】
data: {} || [], // 数据
message: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】
sysMessage: 'success' // 存放响应信息提示,调试使用,中英文都行
... // 其它参数，如 total【总记录数】等
},
msg: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】
sysMsg: 'success' // 存放响应信息提示,调试使用,中英文都行
}
----------------------------------------
【status】:
200: OK 400: Bad Request 500：Internal Server Error
401：Unauthorized
403：Forbidden
404：Not Found
【code】:
1: 获取数据成功 | 操作成功 0：获取数据失败 | 操作失败
1、实际业务开展过程中，可能会出现各种的api不是简单的restful 规范能实现的。
2、需要有一些api突破restful规范原则。
3、特别是移动互联网的api设计，更需要有一些特定的api来优化数据请求的交互。
1)、删除单个 | 批量删除 ： DELETE /v1/product body参数{ids：[]}
2)、页面级API : 把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据
1、前端需要哪些字段，API接口应该返回哪些字段，字段不多也不少。
2、更新功能尽量做到：初次返回的原始数据参数与提交更新的数据参数结构一致。
3、时间参数，尽量以一致格式的字符串传递， 如：
‘2019-01’ | ‘2019/01’
‘2019-01-01’ | ‘2019/01/01’
‘2019-01-01 12:12:12’ | ‘2019/01/01 12:12:12’
1、尽量采用自动化接口文档，可以做到在线测试，同步更新。
2、应包含：接口BASE地址、接口版本、接口模块分类等。
3、每个接口应包含：
接口地址：不包含接口BASE地址。
请求方式: get、post、put、delete等。
请求参数：数据格式【默认JSON、可选form data】、数据类型、是否必填、中文描述。
相应参数：类型、中文描述。
如何优雅的“编写”api接口文档
1. 拼写要准确接口函数一旦发布就不能改了，要保持兼容性，拼写错误也不能改了，所以要仔细检查拼写，否则会被同行嘲笑很多年。
著名悲剧：unix 的 creat
2. 不仅是英文单词不要拼错，时态也不要错。
比如：
返回bool的判断函数，单数要用 is 复数要用are，这样你的命名就和文档中的描述保持了一致性。
表示状态的变量或者函数要注意时态，比如 onXxxxChanged 表示xxx已经变化了，isConnecting表示正在连接。
正确的时态可以给使用者传递更丰富的信息。
3. 函数最好是动宾结构
动宾结构就是 doSomething，这样的函数命名含义明确
比如： openFile, allocBuffer, setName
如果这个函数的动词宾语就是这个对象本身，那么可以省略掉宾语
4. 属性命名最好是定语+名词
比如 fileName, maxSize, textColor
5. 不要用生僻单词，这不是秀英语的地方，也不要用汉语拼音
比如：rendezvous，估计大多数人要去查词典才知道什么意思，这个词源自法语，是约会的意思。
Symbian OS里有个用它命名的函数，开发Symbian的是英国人，也许人家觉得很平常吧，反正我是查了词典才知道的。
6. 不要自己发明缩写
除非是约定俗成已经被广泛使用的缩写，否则老老实实用完整拼写。
坏例子: count-cnt, manager-mngr password-pw button-btn
现代的IDE都有很好的自动完成功能，名字长一点没关系的，可读性更重要。
7. 保持方法的对称性，有些方法一旦出现就应该是成对的，
比如 有open就要有close，有alloc就要有free，有add就要有remove，这些单词基本是固定搭配的，使用者就很容易理解。
如果 open对应clear就有点让人困惑了。 关于接口文档在线和接口文档和接口的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 接口文档在线的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于接口文档和接口、接口文档在线的信息别忘了在本站进行查找喔。
版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。
相关文章
推荐文章
最近发表
