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