接口文档一般是五个大的部分。下面我会一一列出
1.一般来说 (第一页)
首先的是
XXXXX接口规格
|
修订历史记录
日期 |
版本 |
说明 |
作者 |
2019-03-26 |
V0.1 |
xxxxxxx初稿 |
QQQ |
2019-03-26 |
V0.2 |
1.xxxx 2.xxxx 3.xxx |
QQQ |
2019-03-27 |
V0.3 |
1.xxxx 2.xxxx 3.xxx |
QQQ |
2019-03-27 | V0.4 |
1.xxxx 2.xxxx 3.xxx |
QQQ |
|
|
|
|
注意所有的更新的记录中说明都要写完整
2. 第二部分 (一般都是目录)
3. 第三部分
4.第四部分 接口
(1)肯定是要写的
baseurl
/xxxx/xxxx
(2)具体的接口规范
1.XXXXX ------ 这是标题(一般都是啥创建啊,修改啊,查询啥的列表啊)
- 基本信息
接口描述 |
XXXXX(和上面标题一样的) |
URL |
{baseurl}/xxxxx/xxxxxx |
报文格式 |
JSON |
请求方式 |
POST |
- 调用参数
# |
参数名 |
数据类型 |
必须 |
长度 |
说明 |
备注 |
1 |
id |
String |
N |
32 |
id |
|
2 |
name |
String |
Y |
64 |
名称 |
|
3 |
status |
int |
Y |
3 |
使用状态 |
|
4 |
type |
int |
Y |
3 |
种类 |
|
调用样例
http://localhost:8080/xxx/xxxx/xxxx
body
{
"id":"string",
"name":"string",
"no":"string",
"type":0
}
- 返回数据
# |
参数名 |
数据类型 |
必须 |
长度 |
说明 |
备注 |
|
resultCode |
String |
Y |
|
状态码 |
00000表示成功 |
2. |
msg |
String |
Y |
|
返回的消息内容 |
|
3. |
result |
Json |
N |
|
返回内容 |
|
- 返回样例
成功:
{
"resultCode":"00000",
"msg":"Success.",
"result":null
}
失败:
{
"resultCode":"XXXXX",
"msg":"XXXXXX",
"result":null
}
# |
错误编码 |
说明 |
备注 |
1 |
10001 |
xxx.xxx.xxx.exist |
xxxxxx已存在 |
2 |
10002 |
xxx.xxx.xxx.not_exist |
xxxxxx不存在 |
接口文档注意事项:
1.url命名要尊重驼峰原则。
2.接口文档要与接口相对应。
3.get接口时,要把返回的成功样例写完整。
4.get接口时,调用的样例一般只要
http://localhost:8080/xxx/xxx/xxxx?page=1&size=10&name=a&type=1&status=1
即可
5.调用和返回的时间格式一般要统一。返回“yyyy-mm-dd HH:mm:ss”
6.注意若传入参数和返回参数存在层级关系
3. |
result |
Json |
N |
|
返回内容 |
|
3.1 |
Content |
List |
N |
|
数据list |
|
3.1.1 |
id |
String |
Y |
32 |
id |
|
在同一表格中用编号表示上下级