將 OpenAPI 檔案連接到 AI

Apidog MCP Server 可以直接讀取 Swagger 或 OpenAPI Specification (OAS) 檔案，讓 AI 助理能夠獨立於 Apidog 專案或線上文件來處理 API 規格。

先決條件

在設定 MCP 用戶端之前，請確保你具備：

Node.js（版本 18 或更新版本，最好是最新的 LTS 版本）

相容 MCP 的 IDE：

Cursor

VS Code + Cline 外掛

其他支援 MCP 的編輯器

Swagger/OpenAPI 檔案（URL 或本機路徑）

準備你的 OpenAPI 檔案

請確保你具備下列其中一項：

遠端 URL：可公開存取的 OpenAPI 檔案（例如 https://petstore.swagger.io/v2/swagger.json）

本機檔案路徑：你電腦上的 OpenAPI 檔案（例如 ~/data/petstore/swagger.json）

支援的格式： JSON 或 YAML

設定概覽

OpenAPI 檔案的基本 MCP 設定：

macOS / Linux

Windows

{
  "mcpServers": {
    "API specification": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=<oas-url-or-path>"
      ]
    }
  }
}

將 <oas-url-or-path> 替換為：

遠端 URL（例如 https://petstore.swagger.io/v2/swagger.json）

本機檔案路徑（例如 ~/data/petstore/swagger.json）

在 Cursor 中設定 MCP

開啟 MCP 設定

開啟 Cursor 編輯器

點擊設定圖示（右上角）

從左側選單選擇 MCP

點擊 + Add new global MCP server

新增設定

在開啟的 mcp.json 檔案中，新增以下設定。將 https://petstore.swagger.io/v2/swagger.json 替換為你實際的 OpenAPI 檔案路徑或 URL：

macOS / Linux

Windows

{
  "mcpServers": {
    "API specification": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=https://petstore.swagger.io/v2/swagger.json"
      ]
    }
  }
}

驗證設定

透過詢問 AI（在 Agent 模式中）來測試連線：

Please fetch API documentation via MCP and tell me how many endpoints exist in the project

如果 AI 從你的 OpenAPI 檔案回傳正確的 API 資訊，表示連線成功。

重要注意事項

使用多個 OpenAPI 檔案

若要使用多個 OpenAPI 規格檔案，請在設定檔中新增多個 MCP Servers，每個都使用不同的 --oas 參數。

範例：

{
  "mcpServers": {
    "Petstore API": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=https://petstore.swagger.io/v2/swagger.json"
      ]
    },
    "Local API": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=~/data/my-api/openapi.yaml"
      ]
    }
  }
}

檔案路徑和 URL 要求

本機檔案路徑：確保路徑正確且檔案存在

URL：確保它們可公開存取，並回傳有效的 OpenAPI 規格檔案

效能考量

如果你的 OpenAPI 檔案很大或包含複雜的資料結構，MCP server 可能需要較長時間處理。

私有化部署

對於私有化部署，請在 IDE MCP 設定中包含你伺服器的 API 位址：

{
  "mcpServers": {
    "API specification": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=<oas-url-or-path>",
        "--apidog-api-base-url=<your-server-url>"
      ]
    }
  }
}

將 <your-server-url> 替換為你的私有化伺服器 API 位址（以 http:// 或 https:// 開頭）。請確保能夠存取 www.npmjs.com 網路。

其他資料來源

將 Apidog 專案中的 API 規格連接到 AI

將 Apidog 發佈的線上 API 文件連接到 AI

常見問題

Windows 設定問題

如果標準設定在 Windows 上失敗，請使用此替代方案：

{
  "mcpServers": {
    "API specification": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "apidog-mcp-server@latest",
        "--oas=<oas-url-or-path>"
      ]
    }
  }
}

Node.js 版本問題

將 OpenAPI 檔案連接到 AI

先決條件#

準備你的 OpenAPI 檔案#

設定概覽#

在 Cursor 中設定 MCP#

重要注意事項#

使用多個 OpenAPI 檔案#

檔案路徑和 URL 要求#

效能考量#

私有化部署#

其他資料來源#

常見問題#