读懂 Apifox 发布的 API 文档，并按照 API 文档发起请求
很多人第一次接触 API 文档时都会有点懵，密密麻麻的参数、各种状态码、请求头...看起来就头疼。其实 API 文档就是一份"使用说明书"，告诉你如何正确地与服务器对话。今天我们就以 Apifox 发布的 API 文档为例，从零开始学会如何读懂文档并成功发起请求。具体的项目例子你可以访问 API Hub 来随机选一个作为参照，在线 API 文档是通过 Apifox 项目发布的。
API 文档的基本构成
打开一个 Apifox 发布的 API 文档，你会看到页面左侧有接口列表，右侧是详细信息。左侧列出了所有可用的接口，通常按功能模块分组，比如"用户管理"、"订单处理"等。
点击任意一个接口，右侧就会显示这个接口的完整信息。这些信息包含了你与这个接口交互所需要知道的一切：它的请求地址是什么、需要什么入参、会返回什么结果。
每个接口文档的顶部都会显示请求方法和 URL。请求方法就是 GET、POST、PUT、DELETE 这些，它们代表了不同的操作类型。GET 用来获取数据，POST 用来创建新数据，PUT 用来更新数据，DELETE 用来删除数据。URL 就是这个接口的网络地址，用于向服务端请求或更新数据。
解读请求信息
在基本信息下方，会展示请求参数的详细说明。请求参数分为 鉴权（Authorization）、路径参数（Path 参数）、查询参数（Query 参数）、请求头（Header 参数）、请求体（Body 参数） 五个部分。只有在 Apifox 接口设计中有配置数据的部分才会显示，否则不会展示（其他功能同理，反正这个接口有什么一般就需要什么）。
- 鉴权（Authorization）：用于接口访问的身份认证信息，例如 Token 或 API Key。
- 路径参数（Path 参数）：写在 URL 路径中的参数，用来标识资源，例如
/users/{id}。 - 查询参数（Query 参数）：跟在
?后的参数，用来筛选或过滤数据，例如/users?role=admin。 - 请求头（Header 参数）：附加在 HTTP 请求头中的参数，常用于传递语言、格式、版本号等信息。
- 请求体（Body 参数）：请求的主要数据内容，常用于提交表单、JSON 数据等。
知识扩展：理解请求、响应、Body、Header、Auth 等 API 基础知识
理解鉴权要求
鉴权是新手最容易卡住的地方。参数填错了顶多是 400 错误，鉴权搞不对直接就是 401，连接口都调用不了。鉴权信息通常出现在几个地方：文档的 “Authorization” 部分会说明这个 API 使用什么鉴权方式，具体接口的请求头部分一般也会标明需要什么类型的认证。
API Key 是最简单的鉴权方式。你需要先在服务商后台申请一个密钥，然后按要求放在正确位置。有些放在请求头：X-API-Key: your-key，有些放在 URL 参数：?api_key=your-key，还有些放在 Authorization 头：Authorization: ApiKey your-key。
Bearer Token 是目前最常用的方式。Token 通过登录接口获得，格式固定为：Authorization: Bearer your-token。注意 "Bearer" 和 token 之间的空格不能省略。Token 通常有有效期，过期后需要刷新或重新登录。
Basic Auth 直接用用户名密码，需要进行 Base64 编码后放在 Authorization 头中。格式是把 username:password 编码后变成 Authorization: Basic encoded-credentials。
获取鉴权信息时，要注意区分测试环境和生产环境，它们通常有不同的密钥和 token。还要确认你的账号有访问相应接口的权限，有些接口只允许管理员调用。
理解参数说明
参数说明是文档中最重要的部分，它决定了你的请求是否能成功。每个参数都有几个关键属性：参数名、类型、是否必需、描述、示例值。
类型信息很关键。如果参数类型是 integer，你就不能传字符串；如果是 array，你需要传递一个数组；如果是 object，你需要传递一个对象结构。Apifox 通常会提供详细的类型说明，包括数组中元素的类型，对象中各个属性的结构。
必需性标识告诉你哪些参数是必须提供的。缺少必需参数的请求肯定会失败，服务器会返回错误信息。
可选参数可以不传，服务器会使用默认值或者忽略这个参数。
描述信息解释了参数的具体用途和限制。比如密码参数可能会说明最小长度要求，邮箱参数会说明格式要求。这些信息帮你理解参数的业务含义，不只是技术规格。
示例值展示了参数应该长什么样，你可以直接复制示例值来测试接口。但要注意，示例值通常是演示用的假数据，在实际使用时要替换成真实数据。
如果你需要在 IDE 编辑器中通过代码来发起请求，你也可以根据需要，复制“请求示例”里的代码来使用。
分析响应结构
了解了请求怎么发，接下来要看响应怎么收。响应部分通常展示状态码和响应体。
状态码是一个三位数字，告诉你请求的结果。200 表示成功，400 表示客户端错误（比如参数有问题），401 表示认证失败，404 表示资源不存在，500 表示服务器内部错误......如果在接口中写有，那么在“在线文档”中会自动列出对应的状态码以及对应的含义。
响应体包含了服务器返回的具体数据。成功的响应通常包含你请求的数据，失败的响应通常包含错误信息。文档会详细说明响应数据的结构，包括每个字段的含义和类型。
很多接口返回的数据都有固定的格式，比如分页查询会返回 total（总数）、page（当前页）、size（每页大小）、data（数据列表）这样的结构。理解了这些通用格式，读其他接口文档就会容易很多。
实际发起请求
现在可以动手发请求了。最简单的方式是使用 Apifox 自带的在线测试功能。在文档页面右上角通常有个"调试"按钮，点击后会出现一个表单，你可以填入参数值直接测试。
请求成功的前提是填入相关的鉴权信息，比如 API Key、Token 什么的，不然无法请求成功。
如果发布文档的时候选择了多个环境，也可以在右上角进行切换。
错误处理和调试
请求不成功是很正常的事，关键是要会调试。首先检查状态码，它会告诉你问题出在哪个层面。
如果是 401 状态码，通常是鉴权问题。检查 Authorization 头的格式是否正确，Bearer Token 有没有 "Bearer" 前缀，API Key 有没有放在正确的位置。还要确认 token 是否过期，账号是否有相应权限。
如果是 400 状态码，通常是参数问题。检查一下必需参数是否都提供了，参数类型是否正确，参数值是否符合要求。很多时候是因为参数名写错了，或者少了某个必需参数。
如果是 404 状态码，可能是 URL 写错了，或者请求的资源确实不存在。仔细对比一下文档中的 URL 和你实际使用的 URL。
如果是 500 状态码，那是服务器的问题，你能做的就是检查请求是否符合文档要求，然后联系 API 提供方。
响应体中的错误信息也很有用。大多数 API 在出错时会返回详细的错误描述，告诉你具体哪里有问题。比如"缺少必需参数 email"、"用户名已存在"这样的信息。
掌握了这些基本技能，你就能读懂大部分 API 文档并成功发起请求了，不懂的再回过头来看这篇文章《理解请求、响应、Body、Header、Auth 等 API 基础知识》
