接口文档一般是五个大的部分。下面我会一一列出
1.一般来说 （第一页）
首先的是
| XXXXX接口规格
|
修订历史记录
| 日期 |
版本 |
说明 |
作者 |
| 2019-03-26
扫描二维码关注公众号，回复：
5704502 查看本文章
|
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 |
|
在同一表格中用编号表示上下级