¿Cómo se puede usar OpenAPI para crear servidores simulados (mock)? #

Uno de los usos más productivos de un documento OpenAPI es servir como fuente de verdad para un servidor simulado (mock): un servidor que responde a las solicitudes de la API con datos realistas y válidos según el esquema, sin necesidad de una implementación real del backend. Los servidores simulados aceleran el desarrollo en paralelo, permiten que los equipos de frontend trabajen de forma independiente de los de backend y ofrecen un objetivo estable para las pruebas de contrato. Como los documentos OpenAPI describen endpoints, esquemas de solicitud, esquemas de respuesta y ejemplos en un formato legible por máquinas, son la entrada ideal para la generación automatizada de servidores simulados.

Por qué importan los servidores simulados #

En un flujo de trabajo típico API-first, el documento OpenAPI se acuerda antes de que empiece la implementación. Pero los consumidores de esa API (desarrolladores de frontend, equipos móviles, socios de integración) no pueden esperar a que el backend esté operativo. Un servidor simulado cubre esa brecha:

• Los equipos de frontend pueden construir y probar los flujos de la interfaz con respuestas realistas de la API desde el primer día.
• Los equipos de QA pueden escribir y ejecutar pruebas automatizadas antes de que el backend esté listo.
• Los diseñadores de API pueden validar que la forma propuesta de la API sea ergonómica consumiéndola en un cliente real.
• Los portales de documentación pueden ofrecer la funcionalidad “Try it out” contra un mock en lugar de un sistema en producción.
• Las pruebas de contrato pueden verificar que la implementación de un servidor coincide con el documento OpenAPI comparando sus respuestas reales con las que produce el mock.

Cómo permite OpenAPI la simulación #

Un servidor simulado necesita saber:

1. Qué rutas y métodos son válidos.
2. Qué parámetros se esperan.
3. Cómo es la estructura de la respuesta.
4. Qué valores de ejemplo devolver.

OpenAPI 3.x proporciona todo esto. El servidor simulado lee el documento y, para cada solicitud entrante, encuentra la operación correspondiente, valida la solicitud contra los esquemas de parámetros y de cuerpo, y devuelve una respuesta usando una de estas opciones:

• examples explícitos: valores proporcionados por el diseñador de la API en el documento OpenAPI.
• Campos example: valores de ejemplo individuales en las propiedades de un esquema.
• Generación basada en el esquema: sintetizar una respuesta que se ajuste al esquema de respuesta si no se proporciona ningún ejemplo explícito.

Prism: el servidor simulado de OpenAPI más utilizado #

Prism, desarrollado por Stoplight, es el servidor simulado de OpenAPI más utilizado. Es de código abierto, está disponible como herramienta CLI y como imagen de Docker, y admite OpenAPI 2.0, 3.0 y 3.1.

Instalación #

npm install -g @stoplight/prism-cli

Iniciar un servidor simulado #

prism mock openapi.yaml

Prism lee el documento OpenAPI, inicia un servidor HTTP (puerto 4010 por defecto) y responde a las solicitudes según la especificación. Si el documento incluye examples, Prism los devuelve. Si no, genera respuestas conformes al esquema.

Respuestas dinámicas frente a estáticas #

Prism admite dos modos:

• Estático (predeterminado): devuelve el primer ejemplo coincidente o una respuesta generada de forma estática a partir del esquema.
• Dinámico: genera en cada solicitud una respuesta nueva, aleatoria pero válida según el esquema, útil para descubrir casos límite.

Activa el modo dinámico con:

prism mock openapi.yaml --dynamic

Validación de solicitudes #

Prism valida las solicitudes entrantes contra el documento OpenAPI. Si falta un parámetro obligatorio o el cuerpo de una solicitud no coincide con el esquema, Prism devuelve un error 422, lo que lo hace útil no solo como servidor simulado, sino también como proxy de validación durante el desarrollo.

Modo proxy #

Prism también puede actuar como proxy, reenviando las solicitudes a un servidor real mientras valida tanto la solicitud como la respuesta contra el documento OpenAPI:

prism proxy openapi.yaml https://api.example.com

Esto lo convierte en una potente herramienta de pruebas de contrato: cualquier divergencia entre las respuestas del servidor real y el documento OpenAPI se notifica como una infracción.

Stoplight Studio y Stoplight Platform #

Stoplight Studio integra Prism directamente en el editor visual de OpenAPI. Mientras diseñas una API, puedes iniciar un servidor simulado con un clic y probarlo de inmediato en un navegador o con un cliente REST. Esta estrecha integración entre el diseño y la simulación acelera el ciclo de retroalimentación del diseño de API.

Stoplight Platform también ofrece simulación alojada, en la que los servidores simulados se despliegan y actualizan automáticamente cada vez que cambia el documento OpenAPI; es útil para compartir una URL de mock estable con socios externos o portales de documentación.

Mockoon #

Mockoon es una herramienta de servidor simulado de escritorio y CLI con soporte nativo para importar OpenAPI. A diferencia de Prism, Mockoon guarda las configuraciones de los mocks en su propio formato, lo que da a los equipos más control sobre la personalización de las respuestas, incluidos cuerpos de respuesta personalizados, retrasos y reglas que devuelven respuestas distintas según el contenido de la solicitud.

Para importar un documento OpenAPI en Mockoon:

mockoon-cli start --data openapi.yaml

Mockoon es especialmente útil cuando los equipos quieren añadir comportamiento específico del mock sobre la base de OpenAPI, por ejemplo, simulando distintos escenarios de respuesta (éxito, error, vacío) según los valores de los parámetros de consulta.

WireMock y OpenAPI #

WireMock es un framework de mocks basado en Java y ampliamente utilizado. La extensión OpenAPI de WireMock puede generar mapeos de stubs de WireMock a partir de un documento OpenAPI, lo que permite a los equipos que ya usan WireMock (a menudo en entornos Java/Spring) obtener simulación basada en OpenAPI sin cambiar de herramienta.

Microcks #

Microcks es una plataforma de código abierto de simulación y pruebas de API diseñada para entornos empresariales y nativos de la nube. Ingiere documentos OpenAPI (así como AsyncAPI, colecciones de Postman y proyectos de SoapUI) y despliega servicios simulados en Kubernetes. Microcks destaca especialmente en organizaciones que necesitan:

• Simulación multiprotocolo (REST, GraphQL, gRPC, mensajería) desde una sola plataforma.
• Pruebas de contrato a escala en muchos servicios.
• Integración con pipelines de CI/CD mediante su API REST y el soporte de Tekton/GitHub Actions.

Usar los ejemplos de forma eficaz #

La calidad de un servidor simulado está directamente ligada a la calidad de los ejemplos del documento OpenAPI. Buenas prácticas:

example en línea en las propiedades del esquema #

properties:
  id:
    type: string
    format: uuid
    example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  email:
    type: string
    format: email
    example: "jane.doe@example.com"

examples con nombre en las respuestas #

responses:
  "200":
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
        examples:
          active-user:
            summary: An active user
            value:
              id: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
              email: "jane.doe@example.com"
              status: "active"
          suspended-user:
            summary: A suspended user
            value:
              id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              email: "john.smith@example.com"
              status: "suspended"

Los ejemplos con nombre permiten que los servidores simulados devuelvan distintos escenarios según un encabezado de la solicitud (Prism usa Prefer: example=suspended-user), lo que permite a los clientes probar varios estados sin cambiar la configuración del servidor simulado.

Integrar los mocks en CI/CD #

Un patrón habitual es iniciar un servidor simulado de Prism como parte del pipeline de CI/CD y ejecutar pruebas de integración contra él:

# GitHub Actions example
- name: Start mock server
  run: prism mock openapi.yaml &

- name: Wait for mock to be ready
  run: npx wait-on http://localhost:4010

- name: Run integration tests
  run: npm test

Esto garantiza que cada compilación verifique que el código del cliente funciona correctamente contra el contrato de la API, detectando errores de integración antes de que lleguen a producción.

Conclusión #

Los documentos OpenAPI son la base ideal para los servidores simulados. Herramientas como Prism, Mockoon, WireMock y Microcks permiten levantar en minutos un mock realista de una API a partir de un documento OpenAPI. Al invertir en ejemplos completos dentro del documento OpenAPI e integrar los servidores simulados en el flujo de desarrollo y de CI/CD, los equipos pueden reducir drásticamente la fricción del desarrollo paralelo de API y detectar infracciones del contrato mucho antes de que lleguen a producción.

Última actualización: 30 de abril de 2026.