¿Qué es Prism y cómo se puede usar para la simulación (mocking) de API y las pruebas de contrato con OpenAPI? #

Prism es una herramienta de línea de comandos y biblioteca de código abierto creada por Stoplight que lee documentos OpenAPI y los convierte en servidores HTTP funcionales. Cumple dos funciones principales: servidor simulado (mock) (simula respuestas de la API durante el desarrollo) y proxy de validación (se interpone entre un cliente y un servidor real para validar que ambas partes se ajusten al contrato de OpenAPI). Prism hace posible un flujo de desarrollo API-first en el que los equipos de frontend, los equipos móviles y los socios de integración pueden empezar a trabajar con una API antes de que el backend esté implementado.

Instalación de Prism #

Prism se distribuye como un binario independiente y como un paquete de npm:

# Via npm
npm install -g @stoplight/prism-cli

# Or download binary directly
curl -L https://raw.githack.com/stoplightio/prism/master/install | sh

Después de la instalación, comprueba que funciona:

prism --version

Modo de servidor simulado (mock) #

En el modo de servidor simulado, Prism lee un documento OpenAPI e inicia un servidor HTTP que responde a las solicitudes con datos derivados de los campos examples o example del documento, o generados a partir del esquema de la respuesta.

Inicio del servidor simulado #

prism mock openapi.yaml

De forma predeterminada, Prism escucha en http://127.0.0.1:4010. Para documentos OpenAPI remotos o alojados:

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

Cómo se generan las respuestas #

Prism selecciona una respuesta según el siguiente orden de prioridad:

1. Ejemplos estáticos: si la operación define un ejemplo con nombre en examples, Prism lo devuelve. El cliente puede seleccionar un ejemplo concreto mediante el encabezado de solicitud Prefer: example=<name>.
2. Ejemplo en línea: si se define un valor example directamente en el esquema de la respuesta o en el tipo de medio, Prism lo devuelve.
3. Generado a partir del esquema: si no existen ejemplos, Prism genera un valor de respuesta que se ajusta al esquema de la respuesta mediante json-schema-faker.

Selección de un código de estado concreto #

De forma predeterminada, Prism devuelve la primera respuesta correcta (2xx) definida en el documento OpenAPI. Para probar las rutas de error, usa el encabezado Prefer:

curl -H "Prefer: code=404" http://localhost:4010/users/abc

Esto indica a Prism que devuelva la respuesta 404 definida para esa operación, lo que facilita probar el código de manejo de errores sin provocar condiciones de error reales.

Modo dinámico frente a modo estático #

De forma predeterminada, Prism usa el modo estático, que devuelve los mismos valores de ejemplo en cada solicitud. En el modo dinámico, Prism genera valores aleatorios distintos en cada solicitud a partir del esquema:

prism mock --dynamic openapi.yaml

El modo dinámico es útil para realizar pruebas de fuzzing o para comprobar que el código del cliente maneja correctamente datos de formas variadas.

Modo de proxy de validación #

En el modo de proxy, Prism se sitúa entre el cliente y un servidor de API real, reenvía las solicitudes y las respuestas, y valida ambas con el documento OpenAPI.

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

Con esta configuración:

• Las solicitudes entrantes se validan con los esquemas de parámetros y de cuerpo de la solicitud del documento OpenAPI.
• Las respuestas salientes del servidor de origen se validan con los esquemas de respuesta del documento OpenAPI.
• Los fallos de validación se registran y, opcionalmente, hacen que el proxy devuelva un error en lugar de reenviar tráfico que no cumple el contrato.

Esto resulta especialmente útil para:

• Detectar regresiones del backend: si el servidor empieza a devolver una forma distinta de la documentada, Prism lo detecta de inmediato.
• Pruebas de contrato en el cliente: validar que el cliente envía solicitudes que se ajustan a la especificación.
• Pruebas de integración: ejecutar las pruebas de integración del cliente contra un proxy de validación para comprobar a la vez que la integración es correcta y que se cumple la especificación.

Validación de solicitudes #

Prism valida las solicitudes entrantes con el documento OpenAPI. Si una solicitud no supera la validación, Prism devuelve un 400 Bad Request con los detalles de las infracciones:

{
  "type": "https://stoplight.io/prism/errors#UNPROCESSABLE_ENTITY",
  "title": "Invalid request",
  "status": 422,
  "detail": "Your request is not valid and no HTTP validation response was found in the spec, so Prism is generating this error for you.",
  "validation": [
    {
      "location": ["body", "email"],
      "severity": "Error",
      "code": "format",
      "message": "must match format \"email\""
    }
  ]
}

La validación de solicitudes comprueba que:

• Los parámetros obligatorios de ruta, de consulta y de encabezado estén presentes.
• Los valores de los parámetros coincidan con su esquema (tipo, formato, valores de enumeración).
• El cuerpo de la solicitud esté presente cuando se indica required: true.
• Las propiedades del cuerpo de la solicitud coincidan con sus esquemas.

Validación de respuestas #

En el modo de proxy, Prism también valida las respuestas del servidor de origen:

• Los códigos de estado de la respuesta estén documentados en el documento OpenAPI.
• Las propiedades del cuerpo de la respuesta coincidan con el esquema de la respuesta.
• Los encabezados de respuesta obligatorios estén presentes.

De forma predeterminada, los fallos de validación se registran en stderr. Para que Prism rechace las respuestas del servidor de origen que no cumplen el contrato (devolviendo en su lugar un 500), usa la opción --errors:

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

Integración con CI/CD #

El servidor simulado de Prism se puede integrar en los pipelines de CI para ejecutar pruebas automatizadas contra la simulación antes de que el backend real esté disponible:

# GitHub Actions example
jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Prism
        run: npm install -g @stoplight/prism-cli

      - name: Start Prism mock server
        run: prism mock openapi.yaml &
        
      - name: Wait for Prism to be ready
        run: npx wait-on http://localhost:4010

      - name: Run API tests
        run: npm test

Este patrón garantiza que las pruebas de los consumidores de la API se ejecuten en cada PR, lo que ofrece una retroalimentación rápida sobre si el documento OpenAPI tiene el comportamiento esperado antes de que exista un servidor real.

Uso de Prism con varios ejemplos #

OpenAPI 3.x admite varios ejemplos con nombre por respuesta de operación. Prism los expone todos mediante el encabezado Prefer:

responses:
  "200":
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
        examples:
          active:
            summary: An active user
            value:
              id: "u1"
              email: "alice@example.com"
              status: active
          suspended:
            summary: A suspended user
            value:
              id: "u2"
              email: "bob@example.com"
              status: suspended

Para seleccionar el ejemplo suspended:

curl -H "Prefer: example=suspended" http://localhost:4010/users/u2

Esto facilita probar distintos estados de la aplicación sin modificar el código del cliente.

Limitaciones #

• Prism no ejecuta lógica de negocio: solo sirve ejemplos o datos generados. El comportamiento con estado (por ejemplo, un POST que crea un recurso que devuelve un GET posterior) no se admite en el modo de simulación.
• La calidad de los datos generados a partir del esquema depende de lo descriptivos que sean los esquemas de OpenAPI. Los esquemas escasos, con pocas restricciones, producen datos generados de baja calidad.
• Los documentos OpenAPI muy grandes o complejos pueden afectar al rendimiento al iniciar el servidor simulado.

Para necesidades de simulación con estado, herramientas como WireMock o MSW pueden ser complementos más adecuados.

Conclusión #

Prism es una herramienta potente para los equipos que practican el desarrollo API-first. Su modo de servidor simulado desbloquea a los equipos consumidores antes de que exista el backend, mientras que su modo de proxy ofrece una validación continua del contrato contra servidores reales. La combinación de validación de solicitudes, validación de respuestas, selección de ejemplos e integración con CI convierte a Prism en una de las herramientas de pruebas nativas de OpenAPI más completas que existen.

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