编写一份基本的接口文件要注意以下几点：
1.一定要有版本号，因为基本上对应的接口都是刚开发或者待开发的（已经正常使用的接口也不需要你来写文档）不可能一次提供最终版，方便后续更改，同时避免因为修改多次导致双方使用不一样的文档而出错。
2.封皮要有，带公司logo的那种，目录要有，时间要有（创建时间，修改时间）
这几个就是为了让文档看起来更加正式。
3.接口文档最重要的是接口的详细信息，基本上满足以下几点就可以了：
- 接口名称
- 功能说明
- 提供方，调用方
- 接口调用方式（比如是Http还是Webservice）
- 接口调用地址（必要时分别给出测试和生产的）
- 入参列表，出参列表（入参，出参列表最好以表格的形式展现，包括参数类型，参数名【尤其大小写要明确】，名称，能否为空，备注【备注可以列出一些拓展信息，比如参数范围是枚举值的】），如下表所示：
| 字段类型 |
字段名 |
注释 |
是否为空 |
备注 |
| Int |
ID |
工号 |
N |
|
| String |
City |
城市 |
N |
编码详见附录X.X |
| Long |
Type |
类型 |
N |
001:重要 002:一般 |
- 一个调用的样例和返回的样例
4.附录
一些参数的枚举编码表，参考资料等等。