# 选择 OpenAPI 与 API 调试工具

根据验证、协作和契约使用需求，选择现有工具，避免重复配置与泄露凭据。

## 核心步骤

- 根据单次验证或团队协作选择工具。
- 从官方入口获取当前契约或集合。
- 将凭据放入私有环境，运行一次最小请求并核对结果。

## 适用场景与准备

适合希望通过调试工具确认接口契约，或准备生成调用代码的开发者。先选定一个 API，确认产品权限，准备其 AppKey 和所需参数。只阅读契约无需发送请求；进入调试阶段再配置私有凭据。

## 先分清契约与工具

OpenAPI 描述请求方式、参数和响应结构，本身不是权限凭据。Swagger、Postman、Apifox 是查看和调试契约的不同入口。第一次验证请求不必同时配置多套工具，选择当前团队最熟悉的一种即可。

| 需求 | 推荐入口 | 需要注意 |
| --- | --- | --- |
| 给程序或 AI 读取接口契约 | [OpenAPI 规范](https://www.gugudata.com/openapi/gugudata.openapi.3.1.json) | 核对目标 operation 的实际请求方式 |
| 快速查看并尝试请求 | [Swagger](https://www.gugudata.com/swagger) | 发起正式请求可能消耗额度 |
| 团队维护环境与请求集合 | [Postman 官方集合](https://www.postman.com/gugudata/gugudata-official/collection/1163860-22cb92f5-771a-48fd-89c0-f20a0790a8ce/) | 不共享带密钥的环境导出 |
| 阅读文档并调试 | [Apifox / 接口文档](https://doc.gugudata.com/) | 检查当前参数和返回说明 |

## 从接口详情进入

例如在 [天气接口详情](https://www.gugudata.com/api/details/weatherinfo) 中先确认路径与参数，再跳转到调试工具。不要用搜索到的旧代码覆盖详情页当前契约，也不要把 Demo 路径替换成正式路径后直接批量执行。

## 在 Postman 或 Apifox 中准备环境

从官方入口导入或打开集合，检查服务地址和目标请求方法。把 AppKey 放入本地、私有或敏感环境变量，在请求头中引用，不写进集合描述或公共初始值。工具的共享设置不同，导出前再次检查是否包含实际凭据。

运行最小请求，分别检查 HTTP 状态、业务状态和预期字段。如果工具成功而代码失败，对比参数编码、Content-Type、请求头和代理配置，而不是只对比 URL。

## 让 OpenAPI 帮助代码接入

可以从当前 OpenAPI 获取目标操作的字段约束，再交给生成工具或 Coding Agent。生成的客户端仍需要检查超时、错误分支、空值处理及凭据注入方式。不要默认生成器已经理解所有业务状态码和计费边界。

::: note
Swagger 的可执行请求、Postman 的集合运行和 Apifox 的调试都属于真实请求能力，不是自动免费的沙箱。批量运行前逐条确认目标接口、次数和账号权限。
:::

## 常见配置差异

JSON 请求与表单请求不能互换；某些接口要求查询参数，某些要求表单或文件。以 operation 的请求体类型为准。遇到旧集合字段不一致，回到详情和 OpenAPI 核对，再向 [技术支持](https://www.gugudata.com/contact) 提供脱敏差异。