正如每个人都曾回答过三大本我问题：“我是谁？”，“我在哪？”，“我要去哪里？”；一份设计得当的接口文档同样也需要解决它自己的三大问题：“接口是干嘛用的？”，“接口怎么用？”，“使用接口后的返回结果是什么？”

接口文档的组成要素

一份设计得当的接口文档会用自己的方式回答上述问题，它通常会包含以下要素：

  1. 接口简介（回答接口是干嘛用的？）
  2. 定义请求协议（回答接口怎么用？）
  3. 请求地址源
  4. 请求方式
  5. 请求参数
  6. 返回参数示例（回答接口后的返回结果是什么？）
  7. 状态码

了解各个要素的含义后便能够清楚地知悉这个接口所能够提供的服务、接口的使用方法。下文将以 Apifox Echo 接口为例，介绍如何读懂一份接口文档。

1. 接口简介

接口简介回答了接口是干什么的这个问题。在接口文档中，开发者往往会首先查看接口简介来了解接口的功能和用途。因此，编写清晰、准确的接口简介是至关重要的，它可以帮助开发者更好地理解接口，提高开发效率和代码质量，接口的维护者应在文档首页准确说明该接口的用途。

2. 定义请求协议

请求协议本质上是互联网的通讯协议，用以规范各服务间的数据传输与交流方式。在 API 接口中，常见的请求协议有 HTTP、HTTPS、FTP。请求协议是各项 API 接口进行通讯的基础，只有双方共同遵循同一套语言规则才有沟通的可能。

  • HTTP

HTTP（Hypertext Transfer Protocol，全称为“超文本传输协议”）是一种用于传输超媒体文档的应用层协议。它是互联网上应用最为广泛的一种协议，常用于客户端和服务器之间的通信。HTTP 协议以明文方式发送信息，因此很容易被窃听或篡改。

  • HTTPS

HTTPS（Hypertext Transfer Protocol Secure，全称为“超文本传输安全协议”）是一种在互联网中进行安全通信的传输协议，它是 HTTP 协议的安全版。HTTPS 的数据传输经过了加密处理，因此更加安全，可以防止信息被窃听、篡改或伪装。HTTPS 协议通常与 SSL 或 TLS 协议配合使用。

  • FTP

FTP（File Transfer Protocol，全称为文件传输协议）是一种用于在互联网中进行文件传输的协议。它是一种标准的网络协议，可以在不同操作系统之间实现文件的传输。

3. 请求地址源

上街买东西需要找到商铺地址定位。同理，请求地址源就是用来告诉用户在哪个地点可以找到接口的服务方，常见的接口地址为域名或 IP 地址。

4. 请求方式

面对接口的功能，应该采取何种方式进行使用？数据的处理无外乎增删查改四种方法，常见的 API 请求方法包括：新增 (POST)、修改 (PUT)、删除 (DELETE) 和获取 (GET)。

5. 请求参数

了解接口大致的功能与使用方法后，现在需要请求方按照特定的格式填写请求内容。API 接口的本质是预先定义好的函数逻辑，例如某项接口主要提供计算功能，此时需求方希望得到输入 1+1 后的计算结果，其中 1+1 就是请求参数。

在接口请求地址中，有以下使用习惯：

  • 用“?”来表示路径地址结束，后面跟着的都是参数，
  • 用“&”来区分参数个数(GET请求传参方式)。

6. 返回参数示例

需求方根据接口文档发起请求后，如何判断接口是否收到了请求，并且返回了正确的结果？此时便需要接口提供方提供返回参数示例，它可以帮助使用者更好地理解接口的使用方法和参数格式，减少请求参数填写错误的可能性。

同时，参数示例也可以帮助使用者更好地理解接口返回的数据格式和内容，方便后续的数据处理和分析。

7. 状态码

状态码在 API 接口中用于快速向请求方反馈当前请求的处理结果。状态码常见于接口功能异常的场景，好比未接通手机时出现的统一回应模板。

状态码是一个三位数字，第一位数字表示响应类别，后面两位数字是一个自定义的代码，用于具体表示响应的状态。例如，200 表示请求成功，404 表示请求的页面不存在等等。状态码是 API 接口文档中的重要部分，它们可以帮助开发者更好地调试和测试自己的应用程序。

知识扩展：