如何将 API 管理从 Postman 转移到 Apifox
上一篇推文讲到用 Swagger 管理的 API 怎么迁移到 Apifox，有许多同学反馈说能不能介绍一下 Postman 的迁移以及迁移过程中需要注意的事项。那么今天，它来了！
从 Postman 迁移到 Apifox 的方法有两种：
- 导出 Postman 集合 （Collection） 文件再导入到 Apifox
- 通过开放 API 导入
下面详细介绍具体操作。
一、导出 Postman 集合文件后导入
要把 API 手动从 Postman 迁移到 Apifox，需要在 Postman 中先将集合 （Collection） 导出为 JSON 文件，然后再将 JSON 格式的文件导入到 Apfox。具体操作如下：
1、导出 Postman 集合文件
在 Postman 中打开一个项目，在项目的左侧栏中，找到你想要迁移的集合 （Collection） ，点击集合右侧的三个小点图标，选择「Export」。
在弹出的对话框中，选择「Collection v2.1」格式，点击「Export」按钮，选择保存路径并保存为 JSON 文件。
接下来，我们需要将导出的 JSON 文件导入到 Apifox 中。
2、导入到 Apifox
在 Apifox 中打开一个项目，在左侧边栏依次选择「项目设置 -> 导入数据 -> Postman」，在这里，上传之前导出的 JSON 文件。
上传文件后，Apifox 会自动解析并导入，你可以在弹出的预览框中进行进一步的筛选和管理。
导入成功后可以在项目中查看对应的接口，如果在 Postman 的集合或接口中写有 Scripts 脚本，也会一并进行迁移。Apifox 完全兼容 Postman 的脚本语法，所以脚本不需要做其它任何的更改，在进行接口调试时可以直接运行。
在 Postman 中往往会使用一个变量 （例如{{baseUrl}}） 来指定前置 URL（例如 http://127.0.0.1:8080 ） ，迁移到 Apifox 时，它会自动转换为 Apifox 「环境管理」中的「服务」。
Postman 中的变量有三种类型，分别是集合变量、环境变量和全局变量。其中，Postman 的集合变量会被自动迁移到 Apifox 的全局变量里。
但是，Postman 中的全局变量和环境变量不会包含在导出的 JSON 文件中。因此，这些变量需要单独导出为 JSON 文件，然后再迁移到 Apifox。
要导出 Postman 的全局变量，依次选择「Environments -> Globals -> Export」，然后导出为 JSON 文件即可。
要导出 Postman 的环境变量，只需在 Environments 中，点击环境名称右侧的三个小点图标，然后选择「Export」即可。
全局/环境变量的 JSON 文件导出之后，就可以导入到 Apifox 中，在项目的左侧边栏依次选择「项目设置 -> 导入数据 -> Postman」，然后上传已导出的全局/环境变量文件，确定导入即可。
导入完成后，你可在 Apifox 的环境管理中查看导入的变量。注意，导入的只是变量，「前置 URL」还需要手动在这里添加。
并且，如果设置有多个「前置 URL」，还需要在「接口」或者「目录」层级中确认是否是该接口所需的。
二、通过开放 API 导入
除了手动导入文件，Apifox 还提供了一个开放 API 接口，可以直接通过 API 导入 Postman Collection v2 格式的数据，开放 API 文档地址：
介绍 👋 - Apifox 开放 API
具体导入的操作步骤如下：
1、获取 API 访问令牌
在 Apifox 中，点击页面右上角的个人头像，选择「账号设置 -> API 访问令牌」选项，在这里生成一个 API 访问令牌 （access_token） ，该令牌用于身份验证，可根据需要设定令牌有效期。
2、获取项目 ID
在 Apifox 中，选择「项目设置 -> 基本设置」即可查看项目 ID。项目 ID 是每个项目的唯一标识符，在调用 API 时需要用到它，以确保数据导入到正确的项目中。
3、调用开放 API
要将 Postman Collection v2 格式的数据导入到 Apifox 中，可以调用以下接口：
POST https://api.apifox.com/v1/projects/{projectId}/import-postman-collection
通过调用上述接口，可以将数据导入指定项目。下面是相关必需参数的说明：
Path 参数
| 参数名称 | 参数类型 | 是否必需 | 描述 |
|---|---|---|---|
| projectId | String | 必需 | 项目 ID，用于指定要导入数据的目标项目。 |
示例：
https://api.apifox.com/v1/projects/3760990/import-postman-collection
Body 参数
| 参数名称 | 参数类型 | 是否必需 | 描述 |
|---|---|---|---|
| input | String | 必需 | 要导入的字符串化后的 JSON 对象。 |
请求 Body 示例：
{
"input": "{"info":{"name":"Sample Collection","_postman_id":"12345-67890-abcdef-ghijk","description":"This is a sample Postman Collection","schema":"https://schema.getpostman.com/json/collection/v2.1.0/collection.json"},"item":[{"name":"Sample GET Request","request":{"method":"GET","header":[],"url":{"raw":"https://jsonplaceholder.typicode.com/posts","protocol":"https","host":["jsonplaceholder","typicode","com"],"path":["posts"]}},"response":[]}]",
"options": {
"targetEndpointFolderId": 0,
"endpointOverwriteBehavior": "OVERWRITE_EXISTING",
"endpointCaseOverwriteBehavior": "OVERWRITE_EXISTING",
"updateFolderOfChangedEndpoint": false
}
}
Header 参数
除了上述必要的入参，还需要在请求头中携带相关的认证信息，如下：
| 参数名称 | 参数类型 | 是否必需 | 描述 |
|---|---|---|---|
| X-Apifox-Api-Version | String | 必需 | 开放 API 版本号，目前支持的版本为 2024-03-28。 |
| Authorization | Object | 必需 | 身份认证，格式为 Bearer 个人访问令牌，也就是上述第 1 步获取到的 API 访问令牌。 |
示例：
'X-Apifox-Api-Version':'2024-03-28' 'Authorization':'Bearer APS-OVWel6j5103zaaaaaaQle99fGNBw8ucH'
4、返回响应示例
接口调用成功后，将返回一个类似如下示例的 JSON 响应，包含导入过程中的统计信息，如新增、更新和忽略的接口数量等。如果返回错误信息，需要仔细检查入参是否漏了哪些必填的参数，或者检查导入的数据格式是否正确。
{
"data": {
"counters": {
"endpointCreated": 10,
"endpointUpdated": 0,
"endpointFailed": 0,
"endpointIgnored": 0,
"endpointFolderCreated": 0,
"endpointFolderUpdated": 0,
"endpointFolderFailed": 0,
"endpointFolderIgnored": 0,
"endpointCaseCreated": 0,
"endpointCaseUpdated": 0,
"endpointCaseFailed": 0,
"endpointCaseIgnored": 0
}
}
}
5、查看导入结果
导入完成后，可以在 Apifox 对应的项目中查看导入的 API 文档。要了解其它更多详细的入参、响应信息，请参考 Apifox 的开放 API 文档。
常见问题
Postman 中的 Pre-request 脚本，在 Apifox 的哪里？
Pre-request 相当于 Apifox 的「前置操作」，Post-response 相当于 Apifox 的「后置操作」，迁移完成后，你可在对应接口或目录的「前/后置操作」中查看脚本。
Postman 中接口的前置 URL 变量，到哪里去了
在 Postman 中，接口使用变量 （例如{{baseUrl}}） 来存放前置 URL （例如 http://127.0.0.1:8080） 。而在 Apifox 中，前置 URL 独立存放于「环境管理」中的「服务」。在进行迁移时，{{baseUrl}} 会自动转换为 Apifox 中的「服务」。这么做是为了避免两者混淆，明确区分变量和前置 URL，更方便进行管理。
在接口发送请求时，只需在页面右上角切换相应的环境，Apifox 就会自动拼接前置 URL。
并且在微服务架构中，在环境里设置了多个前置 URL 时，还可以根据需要在「接口」或「目录」层级指定对应的服务（前置 URL），非常的方便。
通过以上两种方法，可以顺利地将 API 项目从 Postman 迁移到 Apifox。
