之前使用 Swagger 来管理 API,如何迁移到 Apifox?

如何从 Swagger  迁移至 Apifox

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

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

下面详细介绍具体操作。

方法一:导出 Swagger 文件并导入到 Apifox

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

1. 导出 Swagger 文件

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

导出 Swagger 文件并导入到 Apifox


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

在 Swagger UI 中,将 API 文档导出为.yaml或.json文件


2. 导入到 Apifox

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

之前使用 Swagger 来管理 API,如何迁移到 Apifox


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

上传swagger文件后,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 文档并进行更新。

通过swagger在线链接定时导入Apifox



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

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

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

具体操作步骤如下:

1. 安装 Apifox IDEA 插件

打开 IntelliJ IDEA(版本号需大于 2019.3),点击【Settings -> Plugins】进入插件市场(Marketplace),搜索「Apifox Helper」 并安装,安装完成后重启 IDEA。

通过 IDEA 插件一键上传


2. 配置 API 访问令牌

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

导出 Swagger 文件并导入到 Apifox


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

使用 IDEA 插件一键上传swagger


3. 同步接口

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

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

通过 Apifox IDEA 插件上传 swagger


4. 查看接口文档

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

swagger 文档成功导入 Apifox


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

方法四:通过开放 API 导入

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

通过Apifox开放 API 导入 Swagger/OpenAPI


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

1. 获取 API 访问令牌

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

从 Apifox 获取访问令牌导入 swagger


2. 获取项目 ID

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

从 Apifox 获取项目 ID来导入 swagger


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-openapi


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
String
必需
身份认证,格式为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 文档

常见问题解答

Q: 文件导入时报错怎么办?

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

Swagger文件导入Apifox时报错怎么办

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

在 swagger 中定位错误后再导入 Apifox



总结

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

如果使用中有任何问题或建议,欢迎随时在用户群反馈给我们。更多最佳实践内容,可以前往 Apifox 帮助文档查看~

订阅
qrcode

订阅

随时随地获取 Apifox 最新动态