编写一份基本的接口文档要注意以下几点：
1.一定要有版本号，因为基本上对应的接口都是刚开发或者待开发的（已经正常使用的接口也不需要你来写文档）不可能一次提供最终版，方便后续更改，同时避免因为修改多次导致双方使用不一样的文档而出错。
2.要有目录和时间（创建时间，修改时间）
3.接口文档最重要的是接口的详细信息，基本上满足以下几点就可以了：
· 接口名称
· 功能说明
· 提供方，调用方
· 接口调用方式
· 接口调用地址（必要时分别给出测试和生产的）
· 一个调用的样例和返回的样例
| 接口详情 |
|
| 地址 |
http://www.baidu.com （正式环境） |
| 请求方式 |
GET |
| 参数 |
是否必填 |
说明 |
| idfa |
是 |
广告标识符，只支持单个查询 |
| source |
是 |
渠道来源，具体值在接入时再进行分配 |
| 返回结果 |
格式 |
JSON |
| 状态码 |
10000 |
success（调用成功） |
|
|
10001 |
param error(参数错误) |
|
|
10002 |
query failed（查询失败） |
|
|
10010 |
access prohibited(访问拒绝) |
具体返回结果举例：
1、查询成功
{
"state": 10000,
"message": "success",
"data": {
"BD239708-2874-417C-8292-7E335A537FAD": 1 //已经存在
}
}
{
"state": 10000,
"message": "success",
"data": {
"BD239708-2874-417C-8292-7E335A537FAD": 0 //不存在
}
}
2、接口调用失败
{
"state": 10010,
"message": "access prohibited",
"data": [
]
}
4.附录
一些参数的枚举编码表，参考资料等等。