Cómo generar código cliente desde tu especificación API en Apidog

Tienes un endpoint definido y quieres llamarlo desde tu aplicación. La parte tediosa es traducir la especificación a código funcional: la URL correcta, los encabezados, el token de autenticación y la cadena de consulta, todo cableado en una llamada requests o un fetch. Copia un carácter mal y pasarás veinte minutos preguntándote por qué el servidor devuelve un 401.

Prueba Apidog hoy

No tienes que escribir a mano ese código repetitivo. Si tu API está diseñada en Apidog, la plataforma lee la especificación de tu endpoint y te entrega un fragmento de solicitud listo para pegar en el lenguaje en el que trabajas: cURL para una verificación rápida en la terminal, Python requests para un script, JavaScript fetch o Axios para un frontend.

Esta guía explica cómo generar código desde un endpoint, cuándo enviar la solicitud primero para que el fragmento contenga valores reales y cómo mantener el código generado preciso cuando cambia la especificación. Si necesitas una comparación más amplia, consulta estas herramientas de generación de código API.

La idea se basa en que la especificación sea la única fuente de verdad, el mismo principio detrás de la Especificación OpenAPI. Define correctamente una vez y deriva el código de solicitud a partir de esa definición.

Qué hace realmente el generador de código cliente

Apidog convierte una definición de endpoint en un fragmento de solicitud para un lenguaje y una biblioteca HTTP determinados. Por ejemplo, para GET /orders, puedes elegir Python con Requests y generar una llamada que incluya la ruta, encabezados y parámetros declarados en la especificación.

Es un generador de solicitudes por endpoint. Genera código para realizar una llamada en la sintaxis de la biblioteca que elijas; no genera un SDK completo ni un paquete cliente versionado con modelos tipados, paginación o ayudantes adicionales.

Esto encaja con un flujo de trabajo de desarrollo de API "design-first":

1. Defines el contrato de la API.
2. Generas la solicitud desde ese contrato.
3. Los consumidores parten de la misma definición actualizada.

Dos formas de abrir el generador

Apidog ofrece dos puntos de entrada para el mismo generador.

Desde la documentación

1. Abre la pestaña Documentación de tu API.
2. Selecciona el endpoint.
3. Haz clic en Generar Código Cliente.

Este es el camino más rápido cuando estás revisando la documentación y necesitas una llamada para ese endpoint.

Desde el ejecutor

1. Abre la pestaña Ejecutar.
2. Configura o revisa la solicitud.
3. Haz clic en el icono de código </>.

Usa esta opción cuando ya estás probando la llamada y quieres generar código con la configuración actual.

Ambas rutas abren el mismo panel, donde eliges el lenguaje y la variante HTTP.

Generar una llamada Python para GET /orders

Supongamos un endpoint GET /orders que lista pedidos de un cliente, permite filtrar por estado y admite paginación.

Paso 1: abre el endpoint y elige el lenguaje

Abre la pestaña Documentación del endpoint y haz clic en Generar Código Cliente.

Apidog ofrece varias variantes según tu stack:

• Shell: cURL, cURL-Windows, Httpie, wget y PowerShell.
• JavaScript: Fetch, Axios, jQuery, XHR, Native, Request y Unirest.
• Python: http.client y Requests.
• Java: Unirest y OkHttp.
• Go: nativo.
• PHP: cURL, Guzzle, pecl_http y HTTP_Request2.
• Otros: Swift (URLSession), C (libcurl), C#, Objective-C, Ruby, OCaml, Dart, R y HTTP sin procesar.

Para este ejemplo, selecciona Python y Requests. A partir de la especificación, el fragmento puede verse así:

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())

Puedes copiarlo directamente a un script. El fragmento refleja los parámetros, encabezados y ejemplos definidos en el endpoint.

Paso 2: entiende qué incluye el código generado desde la especificación

El código generado directamente desde la especificación incluye la estructura de la llamada y los valores de ejemplo definidos en el contrato.

No incluye automáticamente:

• Valores reales introducidos durante una ejecución.
• Tokens de autorización activos.
• Encabezados como Authorization: Bearer ... si no forman parte de los valores enviados.

Para un endpoint público, esto puede ser suficiente. Para un endpoint protegido, genera código desde una solicitud ya ejecutada.

Paso 3: envía la solicitud para capturar valores reales

Para obtener un fragmento con parámetros concretos y autenticación, envía primero la solicitud y revisa la pestaña Solicitud Real.

Si trabajas con un enfoque design-first:

1. Define el endpoint en la pestaña Editar.
2. Ve a la pestaña Ejecutar.
3. Revisa los parámetros autocompletados desde la especificación.
4. Añade el token de autenticación.
5. Haz clic en Enviar.

Si trabajas en modo request-first, introduce manualmente los parámetros en la pestaña Ejecutar, añade la autenticación y envía la solicitud.

Después de recibir la respuesta:

1. Abre la pestaña Solicitud Real.
2. Desplázate hasta el bloque de código cliente.
3. Selecciona Python y Requests si es necesario.
4. Copia el fragmento generado.

El resultado incluirá los valores 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())

Trata los tokens reales como secretos. No los subas a Git ni los incluyas en documentación pública. Aplica las mismas precauciones recomendadas por la documentación de Stripe para claves activas.

Manejo de cuerpos de solicitud para POST y PUT

GET /orders no necesita cuerpo de solicitud. Sin embargo, para endpoints como POST /orders o PUT /orders/{id}, debes preparar un cuerpo antes de generar el código.

En la pestaña Ejecutar, puedes crear cuerpos JSON o XML de dos formas:

• Seleccionando un ejemplo definido en la especificación.
• Usando Autogenerar para crear una estructura compatible con el esquema.

El menú Autogenerar incluye dos modos:

• Ejemplos: selecciona un ejemplo de cuerpo predefinido.
• Generar Cada Vez: regenera valores en cada uso mediante reglas de mock compatibles con el esquema.

También puedes controlar la generación desde Preferencia de Autogeneración:

• Usar Valores de Ejemplo Primero
• Usar Valores Predeterminados Primero
• Usar Valor Mock
• Generar Solo Nombres de Campo
• Usar Ejemplo de Solicitud

Usa Usar Valores de Ejemplo Primero cuando tu especificación tenga ejemplos útiles. Usa Usar Valor Mock cuando necesites datos generados para todos los campos.

Las opciones de Autogenerar para cuerpos de solicitud requieren Apidog 2.7.0 o posterior. Si no aparecen, actualiza la aplicación. Una especificación completa con ejemplos —como la que obtienes al autogenerar documentación de API desde OpenAPI— reduce la edición manual del cuerpo.

Para valores que cambian en cada solicitud, como marcas de tiempo o IDs aleatorios:

1. Haz clic en el icono de varita mágica junto a un parámetro.
2. O usa Insertar Valor Dinámico dentro de un cuerpo JSON o XML.
3. Envía la solicitud.
4. Copia el código desde Solicitud Real.

Cuándo usar un fragmento de solicitud y cuándo estructurarlo como lógica de aplicación

Elige un fragmento sencillo —cURL, fetch o requests.get— cuando necesites una acción puntual:

• Depurar un 403.
• Compartir una llamada reproducible en un ticket.
• Probar un endpoint en la terminal.
• Añadir un ejemplo a la documentación.

Usa un bloque más estructurado cuando la llamada forme parte de la aplicación. Por ejemplo, si GET /orders se usa desde varios componentes o servicios, conviene encapsularlo en una función y añadir manejo de errores:

import os
import requests

API_URL = "https://api.example.com"
API_TOKEN = os.environ["API_TOKEN"]

def get_orders(status: str, page: int = 1) -> dict:
    response = requests.get(
        f"{API_URL}/orders",
        params={"status": status, "page": page},
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {API_TOKEN}",
        },
        timeout=10,
    )

    response.raise_for_status()
    return response.json()

Si varios endpoints comparten autenticación o encabezados, centraliza esos valores. Esta guía sobre cómo establecer parámetros globales en Apidog muestra cómo definir encabezados y variables una sola vez.

Mantén el código preciso con el hábito spec-first

El código generado solo es correcto si la especificación está actualizada.

Por ejemplo, si añades un parámetro de consulta region a GET /orders y no regeneras el fragmento, el código copiado quedará desactualizado.

Aplica este flujo:

1. Actualiza la especificación.
2. Prueba el endpoint.
3. Regenera el fragmento.
4. Sustituye el código de ejemplo o la integración afectada.

El modo "spec-first" de Apidog ayuda a mantener la definición como fuente autoritativa.

Para entender o ajustar variantes JavaScript generadas, consulta la documentación de MDN sobre la API Fetch.

Automatiza el flujo de trabajo con la CLI de Apidog

La generación de código es una acción de interfaz gráfica: copias el fragmento desde el panel. La CLI no incluye un comando independiente para emitir código cliente.

Sin embargo, la CLI de Apidog sirve para mantener actualizada la especificación y ejecutar pruebas que validen el comportamiento del endpoint.

Instálala con Node.js v16 o posterior:

npm install -g apidog-cli

Autentícate con un token de acceso:

apidog login --with-token <YOUR_ACCESS_TOKEN>

Después, ejecuta un escenario de prueba guardado para validar el endpoint:

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

Parámetros:

• -t: ID del escenario de prueba.
• -e: ID del entorno.
• -r: reportero (cli, html o junit).

Integra este comando en tu pipeline de CI. La guía de GitHub Actions de la CLI de Apidog explica cómo hacerlo.

La CLI no escribe el código cliente, pero verifica el contrato que ese código consume antes de que alguien regenere un fragmento.

Preguntas frecuentes

¿El código generado incluye mi clave de API y mi token?

No por defecto. El código generado desde la especificación incluye la estructura de la API, no los valores reales ni la autorización activa.

Para incluir el token y los parámetros enviados, ejecuta la solicitud y copia el código desde la pestaña Solicitud Real. Trata cualquier token incluido como un secreto.

¿Para qué lenguajes y bibliotecas puede generar código Apidog?

Apidog admite Shell, JavaScript, Python, Java, Go, PHP, Swift, C, C#, Ruby, Dart, R y más.

Entre las variantes disponibles están cURL, Httpie, wget, Fetch, Axios, requests, http.client, OkHttp, Unirest y Guzzle. Selecciona el lenguaje y la variante desde el panel del generador.

¿Por qué no veo las opciones de autogeneración para cuerpos de solicitud?

Estas opciones requieren Apidog 2.7.0 o posterior. Actualiza la aplicación y revisa la pestaña Ejecutar al configurar un cuerpo JSON o XML.

¿La generación de código cliente es una función de pago?

La documentación de Apidog no establece una distinción entre planes gratuitos y de pago, ni entre versiones alojadas y autoalojadas, para la generación de código cliente. El requisito de versión mencionado es Apidog 2.7.0 o posterior para las opciones de Autogenerar cuerpos.

Puedes descargar Apidog y probar el generador.

¿Cómo verifico que la llamada generada funciona?

Genera el fragmento y valida el endpoint mediante un escenario de prueba guardado. Este tutorial sobre cómo escribir un escenario de prueba con Apidog muestra cómo crearlo.

Después, ejecuta ese escenario en CI con la CLI para detectar contratos rotos antes de regenerar o distribuir código cliente.

Conclusión

Generar código cliente en Apidog convierte una especificación de endpoint en una solicitud lista para pegar en tu lenguaje y biblioteca HTTP.

Para obtener parámetros y autenticación reales, ejecuta primero la solicitud y copia el fragmento desde la pestaña Solicitud Real. Mantén la especificación actualizada, regenera el código cuando cambie el contrato y valida los endpoints con escenarios de prueba.

Descarga Apidog, define GET /orders y genera una llamada cliente funcional en pocos clics.