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

Você tem um endpoint definido e deseja chamá-lo do seu aplicativo. A parte tediosa é traduzir a especificação para um código funcional: a URL correta, os cabeçalhos, o token de autenticação, a string de consulta, tudo conectado a uma chamada requests ou fetch. Copie um caractere errado e você passará vinte minutos se perguntando por que o servidor retorna um 401.

Você não precisa escrever esse boilerplate manualmente. Se sua API for projetada no Apidog, a plataforma lê a especificação do seu endpoint e entrega um trecho de requisição pronto para colar na linguagem em que você trabalha: cURL para uma verificação rápida no terminal, requests do Python para um script, fetch ou Axios do JavaScript para um frontend. Este guia descreve a geração desse código a partir de um endpoint real, quando enviar a requisição primeiro para que o trecho contenha valores reais, e como manter o código gerado preciso conforme sua especificação muda. Se você quiser um panorama mais amplo de opções, nosso resumo de ferramentas de geração de código de API oferece uma visão mais ampla; aqui, focamos na prática com o gerador integrado.

button

A ideia se baseia na especificação como uma única fonte de verdade, o mesmo princípio por trás da OpenAPI Specification. Defina corretamente uma vez, e o código da requisição segue a partir dela.

O que o gerador de código cliente realmente faz

O Apidog transforma uma definição de endpoint em um trecho de requisição por variante de linguagem. Aponte-o para GET /orders, escolha Python e a biblioteca Requests, e ele escreve a chamada que acessa esse caminho com os cabeçalhos e parâmetros que sua especificação declara. É um gerador de requisições: ele produz o código para uma única chamada, na sintaxe da linguagem e da biblioteca HTTP escolhidas.

Defina as expectativas corretamente em um ponto. Este recurso gera o código de requisição ou cliente para um endpoint, não um SDK completo ou um pacote de biblioteca cliente versionado. Se você precisa de uma linha curl, um bloco requests do Python ou um trecho fetch de JS para inserir em seu código, é isso que você obtém. A documentação não descreve um gerador de biblioteca completo, então não espere um SDK tipado para download com modelos e auxiliares de paginação já integrados.

Isso se alinha naturalmente com um fluxo de trabalho de desenvolvimento de API "design-first". Você define o contrato, gera o código da requisição diretamente a partir dele, e cada consumidor começa com a mesma definição precisa em vez de uma captura de tela colada no Slack.

Duas maneiras de abrir o gerador

O Apidog oferece dois pontos de entrada para o mesmo recurso. Use o que melhor se adapta à sua situação atual.

O primeiro é a partir da documentação. Abra a guia Documentação da sua API e clique no botão Gerar Código Cliente no lado direito. Este é o caminho mais rápido quando você está lendo a documentação de um endpoint e deseja a chamada para ele.

O segundo é a partir do executor. Na guia Executar da API, clique no ícone de código </>. Ele fica ao lado de onde você constrói e envia requisições, então é a escolha natural quando você já está testando a chamada.

Ambos abrem o mesmo painel. A partir daí, você escolhe uma linguagem e uma variante, e o Apidog escreve o trecho de código.

Gerar uma chamada cliente Python para GET /orders

Aqui está o fluxo completo com um endpoint realista: uma chamada GET /orders que lista os pedidos de um cliente, filtrados por status e paginados.

Passo 1: abra o endpoint e escolha sua linguagem

Abra a guia Documentação para o endpoint e clique em Gerar Código Cliente. No painel, escolha seu alvo. O Apidog suporta uma longa lista de linguagens e variantes, para que você possa corresponder exatamente à sua stack:

Shell: cURL, cURL-Windows, Httpie, wget, PowerShell
JavaScript: Fetch, Axios, jQuery, XHR, Native, Request, Unirest
Python: http.client, Requests
Java: Unirest, OkHttp
Go: Native
PHP: cURL, Guzzle, pecl_http, HTTP_Request2
Outros: Swift (URLSession), C (libcurl), C#, Objective-C, Ruby, OCaml, Dart, R, além de uma opção HTTP pura

Para este exemplo, escolha Python e a variante Requests. O Apidog gera algo assim a partir da especificação:

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, cole em seu script, e é uma chamada funcional. Esse é o caminho "design-first": o trecho reflete exatamente o que seu endpoint declara.

Passo 2: saiba o que o trecho somente da especificação inclui

Há um detalhe importante a ser entendido antes de colar. O código gerado diretamente da especificação da API inclui apenas a especificação da API, não valores reais de parâmetros de requisição ou seu token de autorização. Você obtém a forma da chamada e quaisquer valores de exemplo definidos na especificação, mas não o cabeçalho Authorization: Bearer ... ao vivo que você precisa para realmente alcançar um endpoint protegido.

Isso é bom para uma chamada sem autenticação ou quando você vai preencher o token manualmente. Para um GET /orders protegido, você quer os valores reais no código.

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

Para obter um trecho que contenha valores de parâmetros reais e informações de autorização, envie a requisição primeiro e, em seguida, leia o código na guia Requisição Real.

Se você estiver trabalhando com "design-first", isso é fácil. Defina o endpoint na guia Editar, clique na guia Executar, e os parâmetros da requisição serão preenchidos automaticamente a partir da especificação. Se preferir configurar as coisas manualmente (modo "request-first"), insira os parâmetros da requisição manualmente na guia Executar. De qualquer forma, adicione seu token de autenticação e, em seguida, clique em Enviar para transmitir a requisição.

Assim que a resposta retornar, mude para a guia Requisição Real e role para baixo para encontrar o código cliente. Agora o trecho gerado inclui os valores concretos e o cabeçalho de autenticação que foram realmente 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())

Essa é a diferença entre os dois caminhos. O modo "design-first" preenche automaticamente os parâmetros da especificação; o modo "request-first" permite que você os digite. Ambos alimentam o mesmo trecho da Requisição Real assim que você clica em Enviar. Trate um token real como o acima como um segredo e mantenha-o fora de qualquer coisa que você faça commit para o git; o mesmo cuidado que a documentação da Stripe recomenda para chaves de produção se aplica aqui.

Lidando com corpos de requisição para POST e PUT

GET /orders não tem corpo, mas no momento em que você gera código para um POST /orders ou um PUT /orders/{id}, você precisa de um corpo de requisição no trecho. O Apidog ajuda você a construir um na guia Executar antes de gerar.

Para corpos JSON ou XML, você tem duas fontes. Use um exemplo predefinido da especificação do endpoint, ou clique em Auto-gerar para criar uma estrutura de corpo que corresponda ao seu esquema. O menu suspenso Auto-gerar oferece dois modos:

Exemplos: selecione manualmente um exemplo de corpo de requisição predefinido.
Gerar a Cada Vez: regenere os dados a cada uso, seguindo regras de mock inteligentes para que você obtenha valores frescos e válidos pelo esquema a cada vez.

Você pode controlar como os dados são produzidos através das subopções de Preferência de Auto-geração: Usar Valores de Exemplo Primeiro, Usar Valores Padrão Primeiro, Usar Valor Mock, Gerar Apenas Nomes de Campo e Usar Exemplo de Requisição. Escolha Usar Valores de Exemplo Primeiro quando sua especificação tiver bons exemplos e você quiser que eles sejam respeitados; escolha Usar Valor Mock quando quiser dados gerados realistas para cada campo.

Uma nota sobre a versão: as opções de Auto-gerar para corpos de requisição exigem o Apidog 2.7.0 ou posterior. Se você não as vir, atualize o aplicativo. Um esquema bem especificado com exemplos, o tipo que você obtém da auto-geração de documentação de API a partir do OpenAPI, faz com que esta etapa produza corpos limpos com quase nenhuma edição manual.

Quando você precisa de um valor que muda a cada requisição, como um timestamp atualizado ou um ID de pedido aleatório, insira um valor dinâmico em vez de codificá-lo diretamente. Clique no ícone da varinha mágica ao lado de uma caixa de entrada de parâmetro, ou use o botão Inserir Valor Dinâmico dentro de um corpo de requisição JSON ou XML. Depois que o corpo estiver pronto, clique em Enviar e, em seguida, leia o trecho finalizado na guia Requisição Real como antes.

Quando usar um trecho de requisição versus uma chamada de modelo de negócio

Uma rápida avaliação: quanto código você deve copiar?

Opte por um único trecho de requisição (cURL, fetch, um simples requests.get) quando estiver fazendo algo pontual. Depurando por que um endpoint retorna um 403, compartilhando uma chamada reproduzível em um ticket, fazendo uma verificação rápida no terminal ou colando um exemplo em sua própria documentação. É auto-contido e não precisa de estrutura adicional.

Incline-se para o código mais completo, no estilo de modelo de negócio (o bloco Axios ou requests com cabeçalhos, parâmetros e tratamento de resposta organizados) quando a chamada estiver dentro da lógica real da aplicação. Se GET /orders for residir em um módulo de serviço que é chamado de três lugares, você vai querer a versão estruturada que pode ser encapsulada em uma função, com tratamento de erros e reutilizável. O gerador oferece ambas as formas dependendo da variante que você escolher; combine a forma com o local onde o código será usado.

Se você estiver chamando os mesmos endpoints com a mesma autenticação em todo um projeto, geralmente é mais limpo centralizar as partes compartilhadas. Nosso guia sobre configurar parâmetros globais no Apidog mostra como definir cabeçalhos e variáveis uma vez para que cada chamada gerada os herde, em vez de repetir o token em cada trecho.

Mantenha o código gerado preciso com o hábito "spec-first"

O código gerado é tão correto quanto a especificação por trás dele. Altere GET /orders para adicionar um parâmetro de consulta region e esqueça de regenerar, e seu trecho copiado estará silenciosamente errado. A solução é tratar a especificação como o que você mantém, e o código como um resultado derivado que você regenera sob demanda. O modo "spec-first" do Apidog mantém a definição autoritativa para que o código de requisição que você gera sempre reflita o contrato atual, e não um obsoleto.

Para a sintaxe dos próprios trechos, a documentação do MDN sobre a Fetch API é uma referência sólida quando você deseja entender ou ajustar as variantes JavaScript que o Apidog produz.

Automatize o fluxo de trabalho com o Apidog CLI

A geração de código em si é uma ação de GUI; você copia um trecho de um painel, e não há um comando CLI separado que emita o código cliente. O que o Apidog CLI faz bem é manter as duas coisas das quais a geração depende: uma especificação atualizada e testes aprovados que comprovam que o cliente gerado realmente funciona.

Instale-o com npm install -g apidog-cli (Node.js v16+) e autentique:

apidog login --with-token <YOUR_ACCESS_TOKEN>

Importe novas alterações de especificação para que o código que você gera permaneça atualizado e execute o cenário de teste salvo que exercita o endpoint que seu cliente chama:

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

Aqui, -t é o ID do cenário de teste, -e é o ID do ambiente e -r é o reporter (cli, html ou junit). Conecte isso ao seu pipeline, da forma que nosso guia Ações do GitHub do Apidog CLI descreve, e cada push verifica se GET /orders ainda se comporta como a especificação promete antes que alguém regenere um cliente a partir dela. O CLI não escreve seu código cliente, mas ele protege o contrato no qual esse código é construído.

FAQ

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

Não por padrão. O código gerado a partir da especificação da API inclui apenas a especificação, não valores reais de parâmetros ou autorização. Para obter um trecho com seu token e valores reais, envie a requisição primeiro e, em seguida, leia o código na guia Requisição Real. Trate qualquer token nesse trecho como um segredo.

Para quais linguagens e bibliotecas o Apidog pode gerar código?

Um conjunto amplo. Shell (cURL, Httpie, wget, PowerShell), JavaScript (Fetch, Axios, jQuery, XHR e mais), Python (http.client e Requests), Java (Unirest, OkHttp), Go, PHP, Swift, C, C#, Ruby, Dart, R e outros. Você escolhe a linguagem e a variante específica no painel do gerador.

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

Essas opções exigem o Apidog 2.7.0 ou posterior. Atualize o aplicativo e elas aparecerão na guia Executar quando você construir um corpo JSON ou XML. Uma vez disponíveis, o menu suspenso Auto-gerar oferece Exemplos e Gerar a Cada Vez, com subopções de preferência para como os valores são produzidos.

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

A documentação do Apidog não traça uma linha entre gratuito e pago ou entre nuvem e auto-hospedado para a geração de código cliente. O único requisito de versão mencionado é que as opções de Auto-gerar para corpos de requisição precisam da versão 2.7.0 ou posterior. Você pode baixar o Apidog e experimentar o gerador sem um plano pago.

Como posso garantir que a chamada gerada realmente funcione?

Gere o trecho, e então verifique o endpoint com um teste salvo. Nosso passo a passo sobre como escrever um cenário de teste com Apidog mostra como construir um, e o CLI pode executá-lo em CI para que um contrato quebrado falhe na build antes que você regenere um cliente a partir dele.

Conclusão

A geração de código cliente no Apidog transforma uma especificação de endpoint em uma requisição pronta para colar em qualquer linguagem em que você trabalhe, e a guia Requisição Real é o truque para obter valores e autenticação reais nesse trecho, em vez de um modelo vazio. Mantenha a especificação como autoritativa, regenere-a quando ela mudar e deixe que um teste salvo confirme que a chamada ainda funciona. Baixe o Apidog para acompanhar, defina seu endpoint GET /orders e copie uma chamada cliente funcional em poucos cliques.