API 管理工具迁移：从 Postman 到 Apifox 的最佳实践

上一篇推文讲到用 Swagger 管理的 API 怎么迁移到 Apifox，有许多同学反馈说能不能介绍一下 Postman 的迁移以及迁移过程中需要注意的事项。那么今天，它来了！

从 Postman 迁移到 Apifox 的方法有两种：

1. 导出 Postman 集合 （Collection） 文件再导入到 Apifox
2. 通过开放 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 文档地址：

https://apifox-openapi.apifox.cn/

具体导入的操作步骤如下：

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。