如何规范编写接口文档 -

编写一份基本的接口文档要注意以下几点：

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.附录

一些参数的枚举编码表，参考资料等等。