Conectar Arquivos OpenAPI à IA

O Apidog MCP Server pode ler diretamente arquivos Swagger ou OpenAPI Specification (OAS), permitindo que assistentes de IA trabalhem com especificações de API independentemente de projetos do Apidog ou documentação online.

Pré-requisitos

Antes de configurar o cliente MCP, certifique-se de ter:

Node.js (versão 18 ou posterior, preferencialmente a versão LTS mais recente)

Uma IDE compatível com MCP:

Cursor

VS Code + plugin Cline

Outros editores compatíveis com MCP

Um arquivo Swagger/OpenAPI (URL ou caminho local)

Preparando Seu Arquivo OpenAPI

Certifique-se de ter uma das seguintes opções:

URL remota: Um arquivo OpenAPI publicamente acessível (por exemplo, https://petstore.swagger.io/v2/swagger.json)

Caminho de arquivo local: Um arquivo OpenAPI em sua máquina (por exemplo, ~/data/petstore/swagger.json)

Formatos compatíveis: JSON ou YAML

Visão Geral da Configuração

A configuração básica do MCP para arquivos OpenAPI:

macOS / Linux

Windows

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

Substitua <oas-url-or-path> por:

Uma URL remota (por exemplo, https://petstore.swagger.io/v2/swagger.json)

Um caminho de arquivo local (por exemplo, ~/data/petstore/swagger.json)

Configurando o MCP no Cursor

Abrir as Configurações do MCP

Abra o editor Cursor

Clique no ícone de configurações (canto superior direito)

Selecione MCP no menu à esquerda

Clique em + Add new global MCP server

Adicionar Configuração

No arquivo mcp.json aberto, adicione a seguinte configuração. Substitua https://petstore.swagger.io/v2/swagger.json pelo caminho ou URL real do seu arquivo OpenAPI:

macOS / Linux

Windows

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

Verificar Configuração

Teste a conexão perguntando à IA (no modo Agent):

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

Se a IA retornar informações corretas da API a partir do seu arquivo OpenAPI, a conexão foi bem-sucedida.

Observações Importantes

Trabalhando com Múltiplos Arquivos OpenAPI

Para usar múltiplos arquivos de especificação OpenAPI, adicione múltiplos servidores MCP no arquivo de configuração, cada um com um parâmetro --oas diferente.

Exemplo:

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

Requisitos de Caminho de Arquivo e URL

Caminhos de arquivo locais: Certifique-se de que o caminho esteja correto e de que o arquivo exista

URLs: Certifique-se de que elas sejam publicamente acessíveis e retornem um arquivo de especificação OpenAPI válido

Considerações de Desempenho

Se o seu arquivo OpenAPI for grande ou contiver estruturas de dados complexas, o servidor MCP poderá levar mais tempo para processá-lo.

Implantação On-Premise

Para implantações on-premise, inclua o endereço de API do seu servidor na configuração MCP da IDE:

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

Substitua <your-server-url> pelo endereço de API do seu servidor on-premise (começando com http:// ou https://). Certifique-se de que haja acesso de rede a www.npmjs.com.

Outras Fontes de Dados

Conectar Especificação de API dentro do Projeto Apidog à IA

Conectar Documentação de API Online Publicada pelo Apidog à IA

Perguntas Frequentes

Problemas de Configuração no Windows

Se a configuração padrão falhar no Windows, use esta alternativa:

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

Problemas de Versão do Node.js

Conectar Arquivos OpenAPI à IA

Pré-requisitos#

Preparando Seu Arquivo OpenAPI#

Visão Geral da Configuração#

Configurando o MCP no Cursor#

Observações Importantes#

Trabalhando com Múltiplos Arquivos OpenAPI#

Requisitos de Caminho de Arquivo e URL#

Considerações de Desempenho#

Implantação On-Premise#

Outras Fontes de Dados#

Perguntas Frequentes#