如何正确规范写接口文档

以你之姓@ 2022-05-29 02:54 173阅读 0赞

## 前言 ##

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

## 开始吧！！！ ##

### 接口1： 查询排重接口 ###

<table> 
 <thead> 
  <tr> 
   <th>接口详情</th> 
   <th></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>地址</td> 
   <td><a href="http://www.baidu.com" rel="nofollow">http://www.baidu.com</a> （正式环境）</td> 
  </tr> 
  <tr> 
   <td>请求方式</td> 
   <td>GET</td> 
  </tr> 
 </tbody> 
</table>

<table> 
 <thead> 
  <tr> 
   <th>参数</th> 
   <th>是否必填</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>idfa</td> 
   <td>是</td> 
   <td>广告标识符，只支持单个查询</td> 
  </tr> 
  <tr> 
   <td>source</td> 
   <td>是</td> 
   <td>渠道来源，具体值在接入时再进行分配</td> 
  </tr> 
 </tbody> 
</table>

--------------------

<table> 
 <thead> 
  <tr> 
   <th>返回结果</th> 
   <th>格式</th> 
   <th>JSON</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>状态码</td> 
   <td>10000</td> 
   <td>success（调用成功）</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>10001</td> 
   <td>param error(参数错误)</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>10002</td> 
   <td>query failed（查询失败）</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>10010</td> 
   <td>access prohibited(访问拒绝)</td> 
  </tr> 
 </tbody> 
</table>

--------------------

具体返回结果举例：

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": [ ] }

如果满意，请打赏博主任意金额，感兴趣的请下方留言吧。可与博主自由讨论哦

<table> 
 <thead> 
  <tr> 
   <th align="center">支付包</th> 
   <th align="center">微信</th> 
   <th align="center">微信公众号</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="center"><img src="https://raw.githubusercontent.com/HealerJean123/HealerJean123.github.io/master/assets/img/tctip/alpay.jpg" alt="支付宝" title=""></td> 
   <td align="center"><img src="https://raw.githubusercontent.com/HealerJean123/HealerJean123.github.io/master/assets/img/tctip/weixin.jpg" alt="微信" title=""></td> 
   <td align="center"><img src="https://raw.githubusercontent.com/HealerJean123/HealerJean123.github.io/master/assets/img/my/qrcode_for_gh_a23c07a2da9e_258.jpg" alt="微信公众号" title=""></td> 
  </tr> 
 </tbody> 
</table>