Como Gerar Código Cliente da Sua API Spec no Apidog

Você tem um endpoint definido e precisa chamá-lo a partir do aplicativo. A parte tediosa é transformar a especificação em código funcional: URL, cabeçalhos, token de autenticação, parâmetros de consulta e uma chamada requests ou fetch. Um caractere incorreto pode resultar em vários minutos investigando um erro 401.

Experimente o Apidog hoje

Você não precisa escrever esse boilerplate manualmente. Se a API foi projetada no Apidog, a plataforma lê a especificação do endpoint e gera um trecho pronto para copiar na linguagem e biblioteca que você usa: cURL, Python requests, JavaScript fetch, Axios e outras. Este guia mostra como gerar o código, quando enviar uma requisição antes para incluir valores reais e como manter os trechos sincronizados com a especificação. Para comparar alternativas, consulte o resumo de ferramentas de geração de código de API.

A abordagem usa a especificação como fonte única de verdade, o mesmo princípio da OpenAPI Specification. Defina o contrato corretamente uma vez; o código da requisição passa a ser derivado dele.

O que o gerador de código cliente faz

O Apidog transforma a definição de um endpoint em um trecho de código para uma chamada HTTP. Por exemplo, ao selecionar GET /orders, Python e a biblioteca Requests, ele gera uma requisição com o caminho, os cabeçalhos e os parâmetros declarados na especificação.

O recurso gera código para uma chamada de endpoint, não um SDK completo e versionado. Use-o quando precisar de:

• Uma linha cURL para testar no terminal;
• Um bloco requests para um script Python;
• Um trecho fetch ou Axios para uma aplicação JavaScript;
• Um exemplo reproduzível para documentação, tickets ou revisão de código.

Não espere um SDK tipado com modelos, paginação e auxiliares já integrados. Para esse fluxo, o gerador é mais útil como uma forma rápida de criar chamadas HTTP consistentes com o contrato da API.

Isso se encaixa em um processo de desenvolvimento de API design-first: defina o contrato, gere a chamada a partir dele e compartilhe uma definição precisa com todos os consumidores.

Duas formas de abrir o gerador

O Apidog oferece dois pontos de entrada para o gerador de código cliente.

Pela documentação

1. Abra a guia Documentação da API.
2. Selecione o endpoint.
3. Clique em Gerar Código Cliente, no lado direito.

Use esse caminho quando estiver lendo a documentação e quiser obter rapidamente um exemplo de chamada.

Pelo executor

1. Abra a guia Executar.
2. Configure ou revise a requisição.
3. Clique no ícone de código </>.

Esse é o caminho mais prático quando você já está testando a chamada. Os dois acessos abrem o mesmo painel, no qual você seleciona linguagem e variante HTTP.

Gerando uma chamada Python para GET /orders

Considere um endpoint GET /orders que lista pedidos de um cliente, com filtro por status e paginação.

Passo 1: selecione a linguagem e a biblioteca

Abra o endpoint na guia Documentação, clique em Gerar Código Cliente e escolha a variante compatível com sua stack.

Algumas opções disponíveis incluem:

• Shell: cURL, cURL-Windows, Httpie, wget e PowerShell;
• JavaScript: Fetch, Axios, jQuery, XHR, Native, Request e Unirest;
• Python: http.client e Requests;
• Java: Unirest e OkHttp;
• Go: Native;
• PHP: cURL, Guzzle, pecl_http e HTTP_Request2;
• Outros: Swift com URLSession, C com libcurl, C#, Objective-C, Ruby, OCaml, Dart, R e HTTP puro.

Para este exemplo, selecione Python e Requests. A partir da especificação, o trecho pode ser semelhante a este:

import requests

url = "https://api.example.com/orders"

querystring = {"status": "shipped", "page": "1"}

headers = {"Accept": "application/json"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

Copie o código para o script e ajuste apenas o que não estiver definido no contrato, como a URL base do ambiente ou credenciais carregadas por variáveis de ambiente.

Passo 2: entenda o que o código baseado apenas na especificação inclui

O código gerado diretamente da especificação inclui a estrutura da chamada:

• Método HTTP;
• Caminho;
• Cabeçalhos definidos no endpoint;
• Parâmetros;
• Valores de exemplo definidos na especificação.

Ele não inclui automaticamente valores reais enviados em uma execução nem um token de autorização ativo. Portanto, em um endpoint protegido, você ainda precisará fornecer algo como:

Authorization: Bearer <TOKEN>

Isso é suficiente para endpoints sem autenticação ou para casos em que você adicionará o token manualmente. Para gerar uma chamada com valores concretos usados em um teste real, envie a requisição primeiro.

Passo 3: envie a requisição para capturar valores reais

Para gerar um trecho com parâmetros efetivamente usados e cabeçalhos de autenticação, siga este fluxo:

1. Abra a guia Executar.
2. Preencha os parâmetros da requisição.
   • Em um fluxo design-first, os parâmetros podem ser preenchidos a partir da especificação.
   • Em um fluxo request-first, insira-os manualmente.
3. Adicione o token ou outro mecanismo de autenticação.
4. Clique em Enviar.
5. Após receber a resposta, abra a guia Requisição Real.
6. Localize o código cliente gerado.

O trecho agora pode incluir os valores enviados:

import requests

url = "https://api.example.com/orders"

querystring = {"status": "shipped", "page": "1"}

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer sk_live_51H8xY2..."
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

A diferença é direta:

• Código da especificação: representa o contrato e seus exemplos.
• Código da Requisição Real: representa a chamada que foi enviada, com os valores concretos usados na execução.

Não faça commit de tokens reais. Trate-os como segredos, seguindo o mesmo cuidado recomendado pela documentação da Stripe para chaves de produção.

Gerando código para POST e PUT

Endpoints como GET /orders normalmente não possuem corpo. Já em operações como POST /orders ou PUT /orders/{id}, o corpo precisa estar definido antes de gerar o código.

Na guia Executar, você pode criar um corpo JSON ou XML de duas formas:

1. Selecionar um exemplo predefinido na especificação;
2. Usar Auto-gerar para montar uma estrutura compatível com o schema.

O menu Auto-gerar oferece:

• Exemplos: permite selecionar manualmente um corpo de requisição predefinido;
• Gerar a Cada Vez: gera novos valores a cada uso, seguindo regras de mock compatíveis com o schema.

Também é possível configurar a Preferência de Auto-geração:

• Usar Valores de Exemplo Primeiro;
• Usar Valores Padrão Primeiro;
• Usar Valor Mock;
• Gerar Apenas Nomes de Campo;
• Usar Exemplo de Requisição.

Use Usar Valores de Exemplo Primeiro quando a especificação tiver exemplos confiáveis. Use Usar Valor Mock quando precisar de dados gerados para testar campos do schema.

As opções de Auto-gerar para corpos de requisição exigem o Apidog 2.7.0 ou posterior. Se elas não aparecerem, atualize o aplicativo. Um schema bem definido, com exemplos úteis — como os produzidos pela auto-geração de documentação de API a partir do OpenAPI — reduz a necessidade de edição manual.

Para campos que mudam a cada execução, como timestamps ou IDs aleatórios:

1. Clique no ícone de varinha mágica ao lado do campo.
2. Ou use Inserir Valor Dinâmico dentro de um corpo JSON ou XML.
3. Envie a requisição.
4. Abra Requisição Real para obter o trecho final.

Quando usar um trecho simples ou código estruturado

A quantidade de código a copiar depende de onde a chamada será usada.

Use um trecho único — cURL, fetch ou requests.get — para tarefas pontuais:

• Depurar um 403;
• Compartilhar uma chamada reproduzível em um ticket;
• Validar um endpoint no terminal;
• Adicionar um exemplo à documentação.

Prefira uma chamada mais estruturada quando ela fizer parte da aplicação. Por exemplo, se GET /orders será reutilizado em vários pontos, encapsule a chamada em uma função ou serviço:

import os
import requests


def list_orders(status: str, page: int = 1) -> dict:
    response = requests.get(
        "https://api.example.com/orders",
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {os.environ['API_TOKEN']}",
        },
        params={
            "status": status,
            "page": page,
        },
        timeout=10,
    )

    response.raise_for_status()
    return response.json()

Centralize autenticação, URL base e cabeçalhos compartilhados quando os mesmos endpoints forem usados em todo o projeto. O guia sobre como configurar parâmetros globais no Apidog mostra como definir cabeçalhos e variáveis uma vez para que as chamadas os herdem.

Mantenha o código preciso com um fluxo spec-first

O código gerado é tão correto quanto a especificação que o originou. Se GET /orders receber um novo parâmetro, como region, mas o trecho não for regenerado, o exemplo copiado ficará desatualizado.

Adote este processo:

1. Atualize a especificação.
2. Revise exemplos, schemas, parâmetros e autenticação.
3. Gere novamente o trecho de código.
4. Execute a requisição.
5. Use a guia Requisição Real se precisar de valores concretos.
6. Atualize o código de integração no projeto.

O modo spec-first do Apidog ajuda a manter a definição como fonte autoritativa, reduzindo o risco de gerar código baseado em um contrato obsoleto.

Para entender ou ajustar variantes JavaScript geradas, consulte a documentação da MDN sobre a Fetch API.

Automatize a validação com o Apidog CLI

A geração do trecho de código é uma ação da interface gráfica. Não há um comando CLI separado para emitir código cliente. Porém, o Apidog CLI ajuda a automatizar duas partes importantes do processo:

• Validar que a especificação continua atual;
• Executar testes que confirmam o comportamento do endpoint.

Instale o CLI com Node.js v16 ou superior:

npm install -g apidog-cli

Autentique usando um token de acesso:

apidog login --with-token <YOUR_ACCESS_TOKEN>

Depois, execute o cenário de teste salvo que exercita o endpoint:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Parâmetros:

• -t: ID do cenário de teste;
• -e: ID do ambiente;
• -r: reporter, como cli, html ou junit.

Integre esse comando ao pipeline de CI. O guia sobre Apidog CLI com GitHub Actions mostra como conectar essa validação ao fluxo de deploy.

O CLI não gera o código cliente, mas protege o contrato no qual esse código se baseia.

FAQ

O código gerado inclui minha chave de API ou token?

Não por padrão. O código gerado a partir da especificação inclui a estrutura da chamada e os exemplos definidos, mas não os valores reais de parâmetros ou autorização.

Para obter um trecho com valores usados na execução, envie a requisição e abra a guia Requisição Real. Nunca exponha tokens reais em repositórios, logs ou documentação pública.

Para quais linguagens e bibliotecas o Apidog gera código?

O gerador oferece opções para Shell, JavaScript, Python, Java, Go, PHP, Swift, C, C#, Ruby, Dart, R e outras linguagens. Entre as variantes estão cURL, Fetch, Axios, requests, OkHttp, Guzzle e URLSession.

Selecione a linguagem e a biblioteca no painel do gerador.

Por que não vejo as opções de Auto-gerar para corpos de requisição?

Essas opções exigem Apidog 2.7.0 ou posterior. Atualize o aplicativo e procure o menu Auto-gerar na guia Executar ao configurar um corpo JSON ou XML.

A geração de código cliente é um recurso pago?

A documentação do Apidog não diferencia planos gratuitos e pagos, nem nuvem e auto-hospedagem, especificamente para geração de código cliente. O requisito de versão mencionado é o Apidog 2.7.0 ou posterior para as opções de Auto-gerar de corpos de requisição.

Você pode baixar o Apidog e testar o gerador.

Como validar se a chamada gerada funciona?

Gere o trecho e valide o endpoint com um cenário de teste salvo. O guia sobre como escrever um cenário de teste com Apidog mostra como criar esse teste. Em seguida, execute-o no CI com o CLI para detectar contratos quebrados antes de regenerar clientes.

Conclusão

A geração de código cliente no Apidog transforma a especificação de um endpoint em uma chamada pronta para copiar. Para incluir parâmetros e autenticação realmente usados, envie a requisição e copie o código da guia Requisição Real.

Mantenha a especificação como fonte de verdade, regenere os trechos quando o contrato mudar e valide os endpoints com testes automatizados. Baixe o Apidog, defina um endpoint como GET /orders e gere uma chamada cliente funcional em poucos cliques.