接口文档大多时候是给开发看的，记住明天给我一根冰糖葫芦

又到周末了，快乐的黑色开始！阿翟兴奋的找朋友上号，朋友尔康却摆了摆手：“等一下，我开电脑开始开发。”

一番激战之后，阿宅又来找朋友了：“你没事吧？” “不是，我被开发喷了，是我需求的bug，老板还骂我，你看。”

为了让小伙伴们尽快上账，我们开始一起回顾：“这是关于基金购买流程的需求，我这里需要明确一下基金委托的类型。我问了我的“爷爷找我爸应用程序端口用得完，终于搞明白了。可以分为买买买、买买买、定投买买，等到上线之后才发现分类不全。” “这东西不是在界面上写得很清楚吗？”

“！！！什么是接口文档！我怎么从来没看过！”

“你，你，你做理财产品半年了，连这点都不知道，那我就大慈大悲地教你，明天记得给我糖葫芦。”

一、什么是接口文件？

首先，什么是接口？你可以简单地把它想象成一个函数，你输入 x，它会告诉你 y。你不需要知道这个函数的逻辑，你只需要知道你输入了什么样的问题，你会得到什么样的答案。

但是怎么丢x，又会出现什么样的y，需要通过接口文档了解。比如下表中，当你根据“输入参数”输入“委托方式”、“分支”等参数时，这个界面会告诉你什么是“资产账户”。

恒生统一接入平台_外围接口规范(futures, options_20210812).xls

二、产品为什么要能够看懂接口文档？

一般来说，有两种类型的接口：

这意味着开发人员甚至团队都是不同的。为了方便交流，有接口文档。从中可以看出，大部分的接口文档都是用来开发的，那产品为什么要看这玩意儿呢？

首先，您确切地知道在迭代或依赖其他系统时可以使用哪些资源。比如下面这个创建微信菜单的界面，从这个界面的参数“type”的描述中，我们可以清楚的知道微信菜单可以实现三种交互：一种是直接点击打开网页; 二是推送消息；三是跳转小程序。

其次，当业务非常复杂时，可以通过接口进行逆向。比如我们在做期货需求的时候，我们并不知道期货产品是属于哪一类的。这时候应用程序端口用得完，我们可以找到恒生的接口，查看它的数据字典，我们发现答案其实很清楚：

再次，在写需求文档或者和开发沟通的时候，发现不清楚的时候，也可以通过文档说清楚。例如，在对内容进行排序时，可能有多个时间：创建时间、更新时间、运行时间等。而且你想调用的时间可能和开发者理解的不一样，那你可以拉出接口文档告诉他我要的是CreateTime。

当然，界面文档还有很多精彩的用途，比如强大的撕逼利器、装逼神器等等，欢迎大家在留言区写下你的文档故事~

三、接口文档呢？

接口文档有这么多好处，那我们该如何阅读呢？这里我们使用微信订阅通知的接口文档作为学习资料。

如上图所示，接口通常分为请求方法、url、请求参数、返回参数四部分：

1）请求方法：常用的方法有以下四种——GET、PUT、POST、DELETE。

这个概念产品经理可以简单理解，一般不用测试

2）url：以微信订阅通知界面的url为例

我们可以将此 URL 分解为 5 个部分：

同样，产品经理不需要很清楚。

3）请求参数和返回参数：请求参数和返回参数分为五列：字段、描述、类型、默认值、是否需要。

字段：类的属性

说明：中文解释

Type：属性的类型，只有四类：String、Number、Object、Array

备注：一些解释，或者写简单的例子

4）返回参数分两种情况讨论：

只返回接口调用成功或失败：代码、原因

返回参数：字段、描述、类型、默认值、是否必填

四、一些值得学习的网址

微信打开文档

金融交易统一接入平台

高德地图API