API文档的结构

什么是API

API，全称是Application Programming Interface，即应用程序编程接口，我们日常中习惯简称为“接口”。其实，接口这个词大家应该不会陌生，比如我们平时比较常用的“USB接口”，就是用来存储和传输数据用的；那什么是API呢，API事实上是在内部预先定义了函数，能够使开发人员无须明白API内部实现的机制，就能够实现某一个功能。

比如说你要实现一个手机注册的功能，那么相应地后台工程师就需要提供一个手机注册的接口，前端开发人员在调用接口实现功能的时候，只需按照既定的规则进行请求即可，不需要去理解该功能的实现逻辑。有了这么一个机制，就使得开发人员间的协作变得非常简洁、高效。

所以，你可以简单地理解为“接口决定了功能”。

那API究竟是用来干嘛的呢？我的理解是，API其实是大自然的搬运工。如何理解这个“搬运工”的概念，其实就是指搬运互联网数据，因为API的本质就是根据调用者的输入内容来返回一些其他内容，不就相当于把数据搬来搬去么（这个搬运工的比喻是不是很形象）。

API文档的结构

通常来说，一份API文档内会包含多个API的信息，单个API的信息通常包括以下内容：

1、接口描述：这个接口是用来干嘛的，以及相关的规则

2、接口地址：以网址的形式展现，你通过发送请求给这个网址来对接口进行交互操作

3、请求方法：常用的有post和get两种方式，一个是读接口(常用get)一个是写接口(常用post)

4、请求参数：请求该接口时，需要提供的参数，参数属性包括名称、类型、是否必填、描述等

5、返回参数：接口正常响应后，返回的内容

6、错误代码：接口请求失败后，返回的错误代码