Necesitas una API falsa para construir. El backend no está listo, o el servicio de terceros tiene un límite de velocidad, o simplemente quieres que tus pruebas se ejecuten sin acceder a un servidor en vivo. La respuesta habitual es un mock. La pregunta es cómo lo pones en marcha.
Puedes hacer clic en una GUI para definir rutas y respuestas predefinidas. Eso está bien una vez. Pero un mock que construyes a mano en una aplicación de escritorio es difícil de reproducir, difícil de versionar e imposible de recrear por sí solo para la integración continua (CI) o un agente de codificación de IA. Un mock que defines desde la línea de comandos es diferente. Es un comando en un script, un paso en una tubería, una línea que un agente puede ejecutar. Lo que tú escribes, una máquina también puede escribirlo.
Esta guía cubre dos rutas. Primero, la ruta general de código abierto: servidores mock de un solo binario que ejecutas directamente desde un archivo, de modo que una especificación o un archivo JSON se convierte en un endpoint en vivo con un solo comando. Luego, la ruta de la CLI de Apidog, que funciona de manera diferente y merece ser entendida en sus propios términos. Si primero quieres conocer el panorama de opciones, nuestro resumen de las mejores herramientas de mock de API y la guía de herramientas de mocking de API REST te darán una visión más amplia.
La ruta general: ejecutar un servidor mock desde un archivo
El mock clásico de CLI es un pequeño binario al que apuntas a un archivo. Dale una especificación o un archivo de datos, y sirve un endpoint HTTP real en un puerto local. Sin proyecto, sin inicio de sesión, sin cuenta. Estas herramientas hacen una cosa: convertir un archivo en una API falsa que puedes llamar. Tres cubren casi todos los casos.
Prism: servir una especificación OpenAPI
Si ya tienes un archivo OpenAPI, Prism de Stoplight es el mock de menor esfuerzo que puedes ejecutar. Lee tus paths, ejemplos y esquemas, y luego sirve respuestas que coinciden con el contrato.
npx @stoplight/prism-cli mock ./openapi.yaml
Eso inicia un servidor en `http://127.0.0.1:4010` con cada operación de tu especificación configurada. Prism devuelve el example que definiste para una respuesta, o genera uno aleatorio válido a partir del esquema si lo omitiste. También valida las solicitudes entrantes contra la especificación, por lo que una llamada malformada recibe un 422 adecuado en lugar de pasar silenciosamente. Llama para comprobar que está vivo:
curl http://127.0.0.1:4010/orders/123
Prism no tiene estado, por lo que un POST no persiste nada. Ese es el punto cuando quieres que el mock sea fiel al contrato. Para una instalación global, ejecuta npm install -g @stoplight/prism-cli y omite el npx.
Mockoon CLI: ejecutar un archivo de datos sin interfaz gráfica
Mockoon CLI ejecuta un mock desde un archivo de datos, ya sea uno que exportaste desde la aplicación de escritorio gratuita de Mockoon o una especificación OpenAPI simple. La aplicación de escritorio te permite construir rutas visualmente; la CLI ejecuta ese mismo entorno sin interfaz gráfica en CI o en un servidor.
npx @mockoon/cli start --data ./env.json
Apuntando --data a un archivo de entorno de Mockoon o a un archivo OpenAPI JSON/YAML, se sirve inmediatamente, por defecto en el puerto 3000. Añade --port para cambiarlo. Si el archivo de datos proviene de una versión anterior de Mockoon, la CLI lo migra en memoria sin tocar el original. Instálalo globalmente con npm install -g @mockoon/cli para un comando mockoon-cli persistente. Esto es una buena opción cuando quieres rutas más ricas y ajustadas manualmente de lo que te ofrece una especificación básica y aún quieres que se ejecuten sin una GUI. Un servidor mock ligero para una API RESTful a menudo encaja aquí.
json-server: simular una API REST desde JSON
Cuando aún no tienes una especificación, json-server es el camino más rápido. Escribes un archivo JSON simple que describe tus datos, y construye una API REST completa alrededor de él.
npx json-server db.json
Dado un db.json con un array de posts, eso sirve http://localhost:3000/posts con GET, POST, PUT, PATCH y DELETE reales. Un POST realmente añade un registro y lo vuelve a escribir en el archivo, por lo que obtienes un comportamiento con estado de forma gratuita, lo que Prism no te dará. También obtienes filtrado, ordenación y paginación a través de parámetros de consulta. Instálalo globalmente con npm install -g json-server si lo quieres siempre en tu PATH.
Esa es la ruta abierta. Cada herramienta es un único binario, se ejecuta desde un archivo y no necesita nada más. La desventaja es que cada una es una isla aparte. El mock vive separado de tu diseño real, tus pruebas y tu documentación, y eres tú quien mantiene sincronizados los archivos y los procesos en ejecución. Si necesitas una coincidencia exacta de solicitudes o una repetición, MockServer y WireMock van más allá, a costa de un entorno de ejecución Java.
La ruta de la CLI de Apidog: importar la especificación, programar las expectativas
Apidog simula de manera diferente, y entender esto correctamente te ahorrará confusiones. La CLI de apidog no inicia un servidor mock local desde un archivo. No existe un apidog mock ./openapi.yaml. En su lugar, Apidog aloja el mock por ti, y la CLI es la forma en que le proporcionas una especificación y programas respuestas personalizadas.
Una nota honesta primero. Apidog no es de código abierto; es un producto comercial con una capa gratuita. Lo que esa capa gratuita más la CLI te ofrece es un proyecto integrado, de modo que el mock, el diseño y las pruebas comparten una única fuente de verdad en lugar de tres archivos y tres procesos separados. Si un mock desechable de un solo archivo es todo lo que necesitas, una herramienta más ligera ganará. Si tu mock debe mantenerse al día con tu API real a medida que cambia, sigue leyendo.
Instala y autentica primero (la guía de instalación de la CLI de Apidog cubre la configuración del token):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Importar una especificación para obtener mocks inteligentes alojados
El primer paso es incorporar tu API a un proyecto. Importa un archivo OpenAPI, y Apidog generará automáticamente una URL de mock para cada endpoint.
apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Aquí es donde Apidog difiere de Prism y json-server. No ejecutas un servidor; la importación te proporciona un mock inteligente alojado para cada operación. El mock inteligente lee los tipos y nombres de los campos de tu esquema, por lo que un campo email devuelve un correo electrónico plausible y un createdAt devuelve una marca de tiempo de aspecto real, no una cadena aleatoria. apidog import también acepta los formatos Swagger 2.0, Postman y Apidog, por lo que una definición existente se convierte en mocks en vivo con un solo comando.
Programar respuestas personalizadas con apidog mock
Los mocks generados automáticamente cubren el caso común. Cuando necesitas una respuesta específica para una solicitud específica, digamos un 200 para un ID de usuario y un 404 para otro, añades una expectativa de mock. Esto es lo que gestiona el grupo de comandos apidog mock, y es CRUD sobre esas expectativas, no un servidor que inicias.
apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
La lista devuelve JSON estructurado, por lo que puedes pasarlo por jq para encontrar el ID de una expectativa y alimentarlo al siguiente comando. Para leer, cambiar o eliminar una:
apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Los subcomandos create y update toman un --file que describe la expectativa. Asegúrate de que la forma sea correcta antes de escribirla, lo cual se cubre a continuación.
Validar el archivo de expectativa antes de escribirlo
No adivines el JSON manualmente. La CLI incluye un esquema para cada escritura, así que obtienes la forma, la rellenas y validas antes de la escritura real. Una expectativa malformada falla rápidamente en lugar de pasar silenciosamente.
apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Obtén el esquema, escribe tu mock.json para que coincida, valídalo y luego créalo. Si la validación devuelve una salida no cero, el pipeline se detiene antes de que un archivo incorrecto llegue a tu proyecto. Ejecuta los mismos tres pasos para las actualizaciones con la clave de esquema mock-update. Cada comando devuelve JSON con un bloque agentHints.nextSteps que te indica a ti, o a un agente, qué ejecutar a continuación, lo que hace que este flujo sea utilizable por herramientas de codificación de IA y no solo por humanos. La guía completa de la CLI de Apidog mapea el resto de los grupos de comandos.
Integrarlo en CI
Ambas rutas encajan en un pipeline porque cada comando tiene un código de salida y una salida de texto. Un mock basado en servidor y una prueba de integración en el mismo trabajo podrían verse así:
# iniciar Prism en segundo plano, luego ejecutar pruebas contra él
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!
npm test
kill $PRISM_PID
El flujo de Apidog tiene una forma diferente: no hay un proceso local que iniciar y detener, porque el mock está alojado. Validas y aplicas las expectativas como un paso de configuración, y tus pruebas acceden directamente a la URL del mock alojado.
# asegurar que la expectativa esté bien formada, luego aplicarla
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
De cualquier manera, nadie hace clic en un botón. Esa es la razón principal para simular desde la CLI: un equipo que prioriza la especificación, un trabajo de CI y un agente de IA pueden todos configurar la misma API falsa con los mismos comandos.
Problemas comunes
Esperar que apidog mock inicie un servidor. No lo hará. No hay apidog mock start, apidog mock serve, ni apidog mock ./file.yaml. Tú apidog import una especificación para obtener mocks alojados, y apidog mock gestiona las expectativas personalizadas sobre ellos. Si quieres un proceso local que inicies desde un archivo, eso es Prism, Mockoon CLI o json-server.
Omitir el paso del esquema en una escritura. apidog mock create y update toman un --file, y una forma incorrecta falla o escribe algo que no pretendías. Siempre ejecuta cli-schema get y cli-schema validate primero. Son dos comandos adicionales y te ahorra una sesión de depuración.
Prism parece vacío porque tu especificación es pobre. El mock de Prism es tan bueno como tus ejemplos. Si una respuesta no tiene example y un esquema vago, obtendrás datos vagos. Añade ejemplos a la especificación y el mock será más preciso.
Expectativas con estado de una herramienta sin estado. Los mocks de contrato de Prism y Apidog no persisten las escrituras. Si necesitas un POST y luego un GET para devolver el nuevo registro, recurre a json-server o a una expectativa de Apidog que devuelva la forma que deseas.
Conclusión
Simular desde la CLI convierte una tarea tediosa de clics en comandos que puedes scriptar, revisar y entregar a CI o a un agente. La ruta abierta te ofrece servidores de un solo binario que ejecutas desde un archivo: Prism para una especificación OpenAPI, Mockoon CLI para un archivo de datos sin interfaz gráfica, json-server para una API REST instantánea desde JSON. La ruta de Apidog funciona de otra manera; importas una especificación una vez para obtener mocks inteligentes alojados, luego programas respuestas personalizadas con apidog mock y la guarda de validación cli-schema.
Elige según lo que ya tengas y dónde deba residir el mock. Si quieres un servidor desechable desde un solo archivo, las herramientas de código abierto son perfectas. Si quieres que el mock se mantenga al día con tu diseño y pruebas en un solo proyecto, descarga Apidog, instala la CLI y configura tus mocks sin tocar el ratón.