如何正确规范写接口文档

Posted 2020-12-04 xiaogou

前言

　　正规的团队合作或者是项目对接，接口文档是非常重要的，一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。下面我将我看到的一篇接口文档做一个总结

开始吧！！！

接口1： 查询排重接口

接口详情
地址	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 //不存在
  }
}

1. 接口调用失败

{
  "state": 10010,
  "message": "access prohibited",
  "data": [

  ]
}