如何將現有的 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.json2 設置定時導入
在 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-collectionBody 參數
| 參數名稱 | 參數類型 | 是否必需 | 描述 |
|---|---|---|---|
| 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 管理體驗。
