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

如何将现有的 Swagger 管理的 API 迁移到 Apifox 呢？本文将为你提供详细的迁移指南，介绍四种主要的方法：

1. 导出 Swagger 文件并导入到 Apifox
2. 通过在线链接定时导入
3. 使用 IDEA 插件一键上传
4. 通过开放 API 导入

下面详细介绍具体操作。

方法一 导出 Swagger 文件并导入

这是最直接的一种方法，适合于一次性迁移，尤其是当你的 API 文档已经比较稳定时。具体操作步骤如下：

1 导出 Swagger 文件

首先，在 Swagger UI 中，将 API 文档导出为 .yaml 或 .json 文件。通常，可以在 Swagger UI 界面左上角找到源文件，然后进行下载。

如果界面没显示有 URL 链接，可以按「F12」或「Ctrl+Shift+i」打开浏览器控制台，然后定位到「Network -> Fetch/XHR」后刷新整个页面，这时候就会出来一个 .json 文件，你可以将其在新窗口中打开并下载。

2 导入到 Apifox

打开 Apifox，进入项目，依次选择「项目设置 -> 导入数据 -> OpenAPI/Swagger」，上传之前导出的 .yaml 或 .json 文件。如果有源文件 URL 且能在公网访问，也可以通过 URL 的方式来手动导入。

上传文件后，Apifox 会自动解析并导入 API 文档，你可以在预览界面进行进一步的编辑和管理。

方法二 通过在线链接定时导入

如果你的 Swagger API 文档经常更新，手动导出和导入可能会显得繁琐。这时候，你可以利用 Apifox 的在线链接定时导入功能，这个方法可以根据定时时间来同步在线的 Swagger 文档。具体操作步骤如下：

1 获取在线链接

确保你的 Swagger 文档可以通过一个公开的 URL 访问。例如：

https://petstore.swagger.io/v2/swagger.json

2 设置定时导入

在 Apifox 中，进入需要定时导入的项目，依次选择「项目设置 -> 导入数据 -> 定时导入」，在这里添加一个新任务，输入你的在线 Swagger 文档 URL（数据源 URL），并设置导入的时间间隔 （例如，每隔 3 小时、每隔 12 小时等） 。保存设置后，Apifox 会自动根据你设定的时间间隔，定时从该 URL 获取最新的 API 文档并进行更新。

方法三 通过 IDEA 插件一键上传

Apifox 的 IDEA 插件 能识别本地 Java 和 Kotlin 项目的源代码，自动生成 API 文档并同步到 Apifox 项目，它支持 SpringBoot 等常见框架，实现了真正的代码零侵入。

对于集成了 Swagger 的项目来说，结合 Apifox 的 IDEA 插件来使用是一种更高效便捷的方法，该插件能够直接从开发环境中将 API 文档上传到 Apifox，简化了迁移过程。具体操作步骤如下：

1 安装 Apifox IDEA 插件

打开 IntelliJ IDEA （版本号需大于 2019.3） ，点击「Settings -> Plugins」进入插件市场 （Marketplace） ，搜索 “Apifox Helper” 并安装，安装完成后重启 IDEA。

2 配置 API 访问令牌

在 Apifox 中，点击页面右上角的个人头像，选择「账号设置 -> API 访问令牌」选项，在这里生成一个 API 访问令牌，可根据需要设定令牌有效期。

在 IDEA 中打开「Apifox Helper」插件配置，输入 API 访问令牌并点击「测试令牌」，测试成功后，点击「Apply」或「OK」按钮保存配置。

3 同步接口

在项目目录树中，右键点击模块节点并选择「Upload to Apifox」以同步模块内全部接口；或者打开 Controller 文件，右键选择「Upload to Apifox」以同步 Controller 内全部接口。

首次同步时，会弹出一个配置界面，你需要选择相应的团队以及相应的项目，接口将默认上传至该项目的根目录。

4 查看接口文档

同步成功后，打开 Apifox，可在项目中查看自动生成的 API 文档。

关于 IDEA 插件配置的更多知识，可访问 Apifox 官方帮助文档的 IDEA 插件模块

方法四 通过开放 API 导入

Apifox 提供了开放 API，允许开发者通过 API 直接导入 Swagger/OpenAPI 格式的 API 数据，开放 API 文档地址为 https://apifox-openapi.apifox.cn/。

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

1 获取 API 访问令牌

在 Apifox 中，点击页面右上角的个人头像，选择「账号设置 -> API 访问令牌」选项，在这里生成一个 API 访问令牌 （access_token） ，该令牌用于身份验证，可根据需要设定令牌有效期。

2 获取项目 ID

在 Apifox 中，选择「项目设置 -> 基本设置」即可查看项目 ID。项目 ID 是每个项目的唯一标识符，在调用 API 时需要用到它，以确保数据导入到正确的项目中。

3 调用开放 API

要将 OpenAPI/Swagger 格式的数据导入到 Apifox 中，可以调用以下接口：

POST https://api.apifox.com/v1/projects/{projectId}/import-openapi

通过调用上述接口，可以将数据导入指定项目。下面是相关必需参数的说明：

Path 参数

参数名称	参数类型	是否必需	描述
projectId	String	必需	项目 ID，用于指定要导入数据的目标项目。

示例：

https://api.apifox.com/v1/projects/3760990/import-postman-collection

Body 参数

参数名称	参数类型	是否必需	描述
input	String/Object	必需	要导入的 OpenAPI/Swagger 数据，可以是 JSON/YAML 字符串或被对象包裹的 URL。
options	Object	可选	高级选项，可设置目标目录 ID、导入接口的覆盖形式等，其内相关参数可在 Apifox 开放 API 文档中详细查看。

请求 Body 示例：

{

"input": {

"url":"https://petstore.swagger.io/v2/swagger.json"

},

"options": {

"endpointOverwriteBehavior": "CREATE_NEW",

"endpointCaseOverwriteBehavior": "CREATE_NEW",

"updateFolderOfChangedEndpoint": false

}

}

注意，input 参数的值可以是字符串，也可以是一个对象。

如果你直接提供 OpenAPI 数据字符串，可以按以下格式传参，该字符串可以是 JSON、YAML 或 X-YAML 格式的 OpenAPI 数据：

{

"input": "{'openapi':'3.0.0','info':{'title':'Sample API','version':'1.0.0'},'paths':{'/sample':{'get':{'summary':'Sample endpoint','responses':{'200':{'description':'successful operation'}}}}}}"

}

如果你提供一个可在公网访问的 URL 地址，该地址指向 OpenAPI/Swagger 格式的数据，那么可以按以下格式传参：

{

"input": {

"url":"https://petstore.swagger.io/v2/swagger.json"

}

}

如果数据源需要鉴权，还可以提供 basicAuth 信息进行认证：

{

"input": {

"url":"https://petstore.swagger.io/v2/swagger.json",

"basicAuth": {

"username": "apiUser",

"password": "securePassword123"

}

}

}

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": 20,

"endpointUpdated": 0,

"endpointIgnored": 0,

"endpointFailed": 0,

"endpointFolderCreated": 3,

"endpointFolderUpdated": 0,

"endpointFolderIgnored": 0,

"endpointFolderFailed": 0,

"schemaCreated": 0,

"schemaUpdated": 7,

"schemaIgnored": 0,

"schemaFailed": 0,

"schemaFolderCreated": 0,

"schemaFolderUpdated": 0,

"schemaFolderIgnored": 0,

"schemaFolderFailed": 0

}

}

}

5 查看导入结果

导入完成后，可以在 Apifox 对应的项目中查看生成的 API 文档。要了解其它更多详细的入参、响应信息，请参考 Apifox 的开放 API 文档。

常见问题

文件导入时报错怎么办？

如下图所示，导入 .yaml 文件时提示解析出错，这说明该文件不符合 OpenAPI 规范，需要修改。

你可以将该文件上传到 https://editor.swagger.io/ 来定位错误，解决完问题后再导入 Apifox。

通过上述四种方法，你可以轻松地将 Swagger 管理的 API 迁移到 Apifox，每种方法都有其适用的场景，你可以根据自己的需求选择最合适的方法。不论是手动导入、在线链接同步、插件上传还是通过开放 API 导入，Apifox 都能提供更高效、更便捷的 API 管理体验。