接口文档一般是五个大的部分。下面我会一一列出
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
}
- 返回数据
# | 参数名 | 数据类型 | 必须 | 长度 | 说明 | 备注 |
| | | Y |
| 状态码 | 00000表示成功 |
2. | | | Y |
| 返回的消息内容 |
|
3. | | | 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. | | | N |
| 返回内容 |
|
3.1 | | | N |
| 数据list |
|
3.1.1 | id | String | Y | 32 | id |
|
在同一表格中用编号表示上下级