如何将 API 管理从 Swagger 转移到 Apifox

最新推荐文章于 2024-07-13 17:17:06 发布

Apifox.

最新推荐文章于 2024-07-13 17:17:06 发布

阅读量1.3k

点赞数 30

文章标签： java 前端后端学习方法改行学it

本文链接：https://blog.csdn.net/m0_71808387/article/details/139438759

版权

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

导出 Swagger 文件并导入到 Apifox
通过在线链接定时导入
使用 IDEA 插件一键上传
通过开放 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 文档地址为介绍 👋 - Apifox 开放 API。

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

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 文档。