Kết nối tệp OpenAPI với AI

Apidog MCP Server có thể đọc trực tiếp các tệp Swagger hoặc OpenAPI Specification (OAS), cho phép trợ lý AI làm việc với đặc tả API độc lập với các dự án Apidog hoặc tài liệu trực tuyến.

Điều kiện tiên quyết

Trước khi cấu hình MCP client, hãy đảm bảo bạn có:

Node.js (phiên bản 18 trở lên, ưu tiên phiên bản LTS mới nhất)

Một IDE tương thích với MCP:

Cursor

VS Code + plugin Cline

Các trình biên tập khác hỗ trợ MCP

Một tệp Swagger/OpenAPI (URL hoặc đường dẫn cục bộ)

Chuẩn bị tệp OpenAPI của bạn

Hãy đảm bảo bạn có một trong các mục sau:

URL từ xa: Một tệp OpenAPI có thể truy cập công khai (ví dụ: https://petstore.swagger.io/v2/swagger.json)

Đường dẫn tệp cục bộ: Một tệp OpenAPI trên máy của bạn (ví dụ: ~/data/petstore/swagger.json)

Định dạng được hỗ trợ: JSON hoặc YAML

Tổng quan cấu hình

Cấu hình MCP cơ bản cho các tệp OpenAPI:

macOS / Linux

Windows

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

Thay thế <oas-url-or-path> bằng:

Một URL từ xa (ví dụ: https://petstore.swagger.io/v2/swagger.json)

Một đường dẫn tệp cục bộ (ví dụ: ~/data/petstore/swagger.json)

Cấu hình MCP trong Cursor

Mở cài đặt MCP

Mở trình biên tập Cursor

Nhấp vào biểu tượng cài đặt (góc trên bên phải)

Chọn MCP từ menu bên trái

Nhấp vào + Add new global MCP server

Thêm cấu hình

Trong tệp mcp.json đã mở, hãy thêm cấu hình sau. Thay thế https://petstore.swagger.io/v2/swagger.json bằng đường dẫn hoặc URL tệp OpenAPI thực tế của bạn:

macOS / Linux

Windows

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

Xác minh cấu hình

Kiểm tra kết nối bằng cách hỏi AI (ở chế độ Agent):

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

Nếu AI trả về thông tin API chính xác từ tệp OpenAPI của bạn, kết nối đã thành công.

Lưu ý quan trọng

Làm việc với nhiều tệp OpenAPI

Để sử dụng nhiều tệp đặc tả OpenAPI, hãy thêm nhiều MCP Server trong tệp cấu hình, mỗi server có một tham số --oas khác nhau.

Ví dụ:

{
  "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"
      ]
    }
  }
}

Yêu cầu về đường dẫn tệp và URL

Đường dẫn tệp cục bộ: Đảm bảo đường dẫn chính xác và tệp tồn tại

URL: Đảm bảo chúng có thể truy cập công khai và trả về một tệp đặc tả OpenAPI hợp lệ

Cân nhắc về hiệu năng

Nếu tệp OpenAPI của bạn lớn hoặc chứa các cấu trúc dữ liệu phức tạp, MCP server có thể mất nhiều thời gian hơn để xử lý.

Triển khai tại chỗ

Đối với các triển khai tại chỗ, hãy đưa địa chỉ API của server vào cấu hình MCP của IDE:

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

Thay thế <your-server-url> bằng địa chỉ API của server tại chỗ của bạn (bắt đầu bằng http:// hoặc https://). Đảm bảo có quyền truy cập mạng tới www.npmjs.com.

Nguồn dữ liệu khác

Kết nối đặc tả API trong dự án Apidog với AI

Kết nối tài liệu API trực tuyến do Apidog xuất bản với AI

Câu hỏi thường gặp

Sự cố cấu hình Windows

Nếu cấu hình tiêu chuẩn không hoạt động trên Windows, hãy sử dụng phương án thay thế này:

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

Vấn đề về phiên bản Node.js

Kết nối tệp OpenAPI với AI

Điều kiện tiên quyết#

Chuẩn bị tệp OpenAPI của bạn#

Tổng quan cấu hình#

Cấu hình MCP trong Cursor#

Lưu ý quan trọng#

Làm việc với nhiều tệp OpenAPI#

Yêu cầu về đường dẫn tệp và URL#

Cân nhắc về hiệu năng#

Triển khai tại chỗ#

Nguồn dữ liệu khác#

Câu hỏi thường gặp#