Apidog é uma plataforma de colaboração e gerenciamento de API que suporta a importação de especificações de API em diversos formatos. Ele pode importar diretamente quase todos os formatos de especificação de API populares, incluindo OpenAPI/Swagger, Postman Collections, arquivos HAR e comandos cURL.
No entanto, em muitos projetos reais, o principal desafio não é sobre como importar especificações de API — é que não há especificações de API disponíveis para importar em primeiro lugar. Alguns sistemas mais antigos ou legados nunca mantiveram documentação de API e não possuem arquivos OpenAPI ou Swagger.
Nesses casos, se você precisa reconstruir rapidamente a documentação de API ausente ou criar casos de teste para que os testadores possam trabalhar com dados reais, usar uma ferramenta de captura de pacotes costuma ser a abordagem mais rápida.
Ao capturar o tráfego HTTP/HTTPS da aplicação, filtrar as requisições úteis, exportá-las como HAR ou cURL e, em seguida, importá-las para o Apidog, você pode gerar rapidamente a documentação da API e lançar as bases para futuros testes de API.
Existem muitas ferramentas disponíveis para gravação de tráfego. Este artigo usa o Charles Proxy como exemplo para demonstrar as operações específicas envolvidas, mas você também pode usar alternativas como Proxyman, Fiddler ou as ferramentas de desenvolvedor integradas ao seu navegador para captura de pacotes. O fluxo de trabalho principal é essencialmente o mesmo em todas essas ferramentas.
Instalação e Configuração Básica do Charles
Charles oferece uma avaliação gratuita de 30 dias. Você pode baixar a versão mais recente do site oficial e instalá-la em seu sistema.
Ao iniciar o Charles pela primeira vez, ele pode perguntar se deve configurar automaticamente as configurações de Rede. É recomendável selecionar "Grant Privileges" (Conceder Privilégios) para conceder as permissões necessárias. Isso permite que o Charles capture automaticamente o tráfego HTTP do seu sistema.
Instalando o Certificado Raiz do Charles para Captura HTTPS
Para capturar tráfego HTTPS, você precisa instalar o certificado raiz do Charles. Esta etapa é essencial porque a maioria das APIs modernas usa HTTPS.
No macOS:
- Clique em "Help → SSL Proxying → Install Charles Root Certificate" (Ajuda → Proxy SSL → Instalar Certificado Raiz do Charles) na barra de menu
- O aplicativo Acesso às Chaves será aberto automaticamente
- Procure e localize o certificado Charles Proxy
- Dê um clique duplo nele e altere a configuração de confiança para "Always Trust" (Sempre Confiar)
No Windows:
- Clique em "Help → SSL Proxying → Install Charles Root Certificate" (Ajuda → Proxy SSL → Instalar Certificado Raiz do Charles) na barra de menu
- Durante o processo de instalação, instale o certificado no armazenamento "Trusted Root Certification Authorities" (Autoridades de Certificação Raiz Confiáveis)
Habilitando o Proxy SSL
Após a instalação do certificado, você precisa habilitar o proxy SSL:
- Selecione Proxy → SSL Proxying Settings (Proxy → Configurações de Proxy SSL) na barra de menu do Charles
- Marque a opção "Enable SSL Proxying" (Habilitar Proxy SSL)
3. Adicione os nomes de domínio (Host) e portas (Porta 443) que você deseja capturar à lista
4. Você também pode usar * para monitorar todos os domínios
Após a conclusão da configuração, o Charles pode capturar requisições e respostas HTTP/HTTPS completas.
Dica: Se você não tiver certeza de quais domínios sua aplicação usa, você pode primeiro operar a aplicação livremente e depois observar as requisições em "Encrypted" (Criptografado) na lista de sessões do Charles. Anote os domínios correspondentes e adicione-os às configurações de SSL Proxying do Charles.
Registrando o Tráfego da API da Sua Aplicação
Inicie a aplicação ou página da web que você deseja analisar e interaja com vários recursos, como fazer login, consultar dados, enviar formulários ou fazer upload de arquivos. A árvore de sessões no lado esquerdo do Charles será atualizada em tempo real, agrupando as requisições por domínio e URL.
Ao selecionar uma requisição específica, o painel direito exibe as informações básicas e o conteúdo da resposta dessa requisição. Na aba Contents (Conteúdo), JSON e outras respostas são recolhidos em uma estrutura de árvore, facilitando a compreensão rápida da estrutura e dos campos dos dados.
Filtrando e Exportando Endpoints de API
Após a conclusão da gravação, você pode descobrir que um grande número de requisições foi capturado. Além das chamadas de API reais, há várias requisições de recursos estáticos, chamadas de serviços de terceiros e outros tráfegos de rede. Neste ponto, você precisa filtrar e reter apenas os endpoints que lhe interessam.
Opções de Filtragem
1. Focar em domínios ou caminhos específicos:
Clique com o botão direito em um domínio ou caminho e selecione "Focus" (Focar)
O Charles manterá apenas as requisições sob esse nó, tornando sua análise conveniente
2. Remover requisições não relacionadas:
Clique com o botão direito em requisições não relacionadas e selecione "Clear" (Limpar) para removê-las
Ou selecione várias requisições e exclua-as em massa
3. Lidar com problemas de cache:
Se o cache fizer com que HTML ou JSON não sejam exibidos corretamente, clique com o botão direito e selecione "No Caching" (Sem Cache)
Isso faz com que o Charles ignore o cache em requisições subsequentes, permitindo que você capture o conteúdo completo da resposta
Exportando como Arquivo HAR
Após a conclusão da filtragem, exporte suas sessões selecionadas:
- Selecione as sessões que deseja exportar:
Você pode selecionar um nó de domínio inteiro, ou
Mantenha pressionado Cmd (Mac) ou Ctrl (Windows) e selecione requisições específicas individualmente
Selecione File → Export Session (Arquivo → Exportar Sessão) na barra de menu
Na caixa de diálogo de exportação, escolha exportar no formato "HTTP Archive (.har)" para criar um arquivo HAR
Importando para o Apidog para Gerar Automaticamente a Documentação da API
Agora é a hora de importar o tráfego capturado para o Apidog:
- Abra o cliente Apidog
2. Vá para Project Settings → Import Data → .har File (Configurações do Projeto → Importar Dados → Arquivo .har)
3. Selecione o arquivo HAR que você exportou do Charles
O Apidog analisará automaticamente o conteúdo do arquivo e exibirá as informações do endpoint detectado na área de visualização, incluindo:
- O número de endpoints detectados
- Métodos de requisição (GET, POST, PUT, DELETE, etc.)
Durante o processo de importação, você pode configurar opções como:
- Em qual módulo importar
- Se deve sobrescrever endpoints existentes
Após a conclusão da importação, você pode visualizar os endpoints no módulo correspondente.
Refinando e Otimizando a Documentação da API
A documentação de API gerada automaticamente é um ótimo ponto de partida, mas geralmente requer ajustes adicionais para atender aos seus requisitos de negócio. Aqui estão algumas melhorias comuns:
- Melhorar os nomes dos endpoints: Altere nomes genéricos para nomes mais descritivos
- Adicionar descrições de parâmetros: Documente o que cada parâmetro faz e quando usá-lo
- Refinar os componentes de resposta: Organize os componentes de resposta para corresponder à sua lógica de negócio
- Adicionar exemplos: Inclua exemplos de requisições e respostas
- Configurar autenticação: Se um endpoint exigir autenticação, configure as informações correspondentes nas variáveis de ambiente ou configurações de autenticação do Apidog. Isso garante que suas chamadas de API funcionem corretamente durante o teste.
Conclusão Final
Ao registrar o tráfego HTTP/HTTPS usando ferramentas de captura de pacotes e, em seguida, importar para o Apidog, você pode gerar rapidamente a documentação da API e fornecer suporte de dados reais para testes.
Seja um navegador, cliente desktop ou aplicativo móvel, este método pode reduzir significativamente o tempo gasto na preparação da documentação da API e permitir que sua equipe comece rapidamente com os testes e desenvolvimento da API.