Prism — OpenAPI Mock Server and Contract Validator

Prism by Stoplight is an open-source CLI tool that turns your OpenAPI spec into a real HTTP mock server in one command. It also operates as a validating proxy that checks whether your real API adheres to its OpenAPI contract — catching spec drift and schema violations before they reach production.

What is Prism?

Prism is maintained by Stoplight (the company behind Stoplight Studio, the API design platform). It is a Node.js CLI that reads an OpenAPI 2.x or 3.x specification file and provides two core capabilities: a mock server that generates HTTP responses from the spec, and a validating proxy that forwards requests to a real backend while checking that all traffic conforms to the spec.

The key difference from tools like Mockoon or Hoppscotch is that Prism is spec-driven. You do not manually define routes and responses — Prism derives everything from your OpenAPI spec. This makes it ideal for API-first workflows where the spec is the single source of truth. When the spec and the implementation disagree, Prism surfaces the violation immediately.

Key Features

• Mock mode — starts a real HTTP server serving responses from OpenAPI examples or dynamically generated data
• Proxy mode — sits in front of a real API and validates every request and response against the spec
• Request validation — validates method, path, query parameters, headers, and request body against the spec
• Response validation — checks that the real API response matches the declared schema, status code, and content type
• Dynamic generation — with --dynamic, Prism generates random but schema-valid response data using Faker
• OpenAPI 2.x and 3.x — supports both Swagger 2.0 and OpenAPI 3.0/3.1 specifications
• Multiple specs — merge multiple OpenAPI files into a single mock server
• Content negotiation — respects Accept headers and returns the appropriate response format
• Verbose logging — detailed logs of every request, response, and validation error
• Docker image — official stoplight/prism Docker image for containerized environments

Installation

# Install Prism CLI globally
npm install -g @stoplight/prism-cli

# Or run with npx (no install required)
npx @stoplight/prism-cli mock api.yaml

Mock Mode — Serve Responses from Your Spec

# Start a mock server from an OpenAPI 3.x spec
prism mock api.yaml

# Mock on a custom port
prism mock api.yaml --port 4010

# Mock with dynamic response generation (uses x-faker or spec examples)
prism mock api.yaml --dynamic

# Mock multiple specs at once
prism mock api.yaml users.yaml --port 4010

Proxy Mode — Validate a Real API

# Proxy mode: validate real API requests/responses against OpenAPI spec
prism proxy api.yaml https://api.example.com --port 4010

# Requests go through: client -> Prism (4010) -> real API -> Prism -> client
# Prism validates both request and response against your spec
# Violations are logged with detailed error messages

Minimal OpenAPI Spec Example

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required: [id, email]
                  properties:
                    id:
                      type: integer
                      example: 42
                    email:
                      type: string
                      format: email
                      example: [email protected]

With the spec above, running prism mock api.yaml immediately starts a server that returns the example values defined in the spec. A GET request to /users returns the example user array without any additional configuration.

Prism vs Mockoon vs MSW

Use Cases

• API-first development: design the OpenAPI spec first, then let Prism serve a mock for parallel frontend and backend work
• Contract testing: use Prism proxy mode to verify that the real backend matches the agreed spec
• CI/CD validation: run Prism proxy in front of staging API and fail the build when spec violations are detected
• Consumer-driven contract checks: validate that third-party API responses match the schema you depend on
• Catching breaking changes: compare spec versions and use proxy mode to detect regressions in production APIs
• Generating realistic test data from OpenAPI schemas with the --dynamic flag