What is Prism and how can it be used for API mocking and contract testing with OpenAPI? #

Prism is an open-source command-line tool and library built by Stoplight that reads OpenAPI documents and turns them into functional HTTP servers. It serves two primary roles: mock server (simulating API responses during development) and validation proxy (standing between a client and a real server to validate that both sides conform to the OpenAPI contract). Prism enables an API-first development workflow where frontend teams, mobile teams, and integration partners can begin building against an API before the backend is implemented.

Installing Prism #

Prism is distributed as a standalone binary and as an npm package:

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

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

After installation, verify it works:

prism --version

Mock Server Mode #

In mock server mode, Prism reads an OpenAPI document and starts an HTTP server that responds to requests with data derived from the document’s examples, example fields, or generated from the response schema.

Starting the Mock Server #

prism mock openapi.yaml

By default Prism listens on http://127.0.0.1:4010. For remote or hosted OpenAPI documents:

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

How Responses Are Generated #

Prism selects a response using the following priority order:

1. Static examples — If the operation defines a named example in examples, Prism returns it. The client can select a specific example using the Prefer: example=<name> request header.
2. Inline example — If a example value is defined directly on the response schema or media type, Prism returns it.
3. Schema-generated — If no examples exist, Prism generates a response value that conforms to the response schema using json-schema-faker.

Selecting a Specific Status Code #

By default Prism returns the first successful (2xx) response defined in the OpenAPI document. To test error paths, use the Prefer header:

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

This instructs Prism to return the 404 response defined for that operation, making it straightforward to test error-handling code without triggering real error conditions.

Dynamic vs Static Mode #

By default Prism uses static mode, returning the same example values on every request. In dynamic mode, Prism generates different random values on each request using the schema:

prism mock --dynamic openapi.yaml

Dynamic mode is useful for fuzzing or testing that client code handles varied data shapes correctly.

Validation Proxy Mode #

In proxy mode, Prism sits between the client and a real API server, forwarding requests and responses while validating both against the OpenAPI document.

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

With this setup:

• Incoming requests are validated against the OpenAPI document’s parameter and request body schemas.
• Outgoing responses from the upstream server are validated against the OpenAPI document’s response schemas.
• Validation failures are logged and, optionally, cause the proxy to return an error rather than forwarding non-conformant traffic.

This is particularly useful for:

• Catching backend regressions — if the server starts returning a different shape than documented, Prism catches it immediately.
• Client-side contract testing — validating that the client sends requests that conform to the spec.
• Integration testing — running client integration tests against a validation proxy to simultaneously test integration correctness and spec conformance.

Request Validation #

Prism validates incoming requests against the OpenAPI document. If a request fails validation, Prism returns a 400 Bad Request with details of the violations:

{
  "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\""
    }
  ]
}

Request validation checks:

• Required path, query, and header parameters are present.
• Parameter values match their schema (type, format, enum values).
• Request body is present when required: true.
• Request body properties match their schemas.

Response Validation #

In proxy mode, Prism also validates responses from the upstream server:

• Response status codes are documented in the OpenAPI document.
• Response body properties match the response schema.
• Required response headers are present.

Validation failures are logged to stderr by default. To cause Prism to reject non-conformant upstream responses (returning a 500 instead), use the --errors flag:

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

Integration with CI/CD #

Prism’s mock server can be integrated into CI pipelines to run automated tests against the mock before the real backend is available:

# 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

This pattern ensures that API consumer tests run on every PR, providing fast feedback on whether the OpenAPI document has the expected behavior before any real server exists.

Using Prism with Multiple Examples #

OpenAPI 3.x supports multiple named examples per operation response. Prism exposes all of them via the Prefer header:

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

To select the suspended example:

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

This makes it easy to test different application states without modifying the client code.

Limitations #

• Prism does not execute business logic — it only serves examples or generated data. Stateful behavior (e.g., a POST creating a resource that a subsequent GET returns) is not supported in mock mode.
• Schema generation quality depends on how descriptive the OpenAPI schemas are. Sparse schemas with few constraints produce low-quality generated data.
• Very large or complex OpenAPI documents may have performance implications when starting the mock server.

For stateful mocking needs, tools like WireMock or MSW may be more appropriate complements.

Conclusion #

Prism is a powerful tool for teams that practice API-first development. Its mock server mode unblocks consumer teams before the backend exists, while its proxy mode provides continuous contract validation against real servers. The combination of request validation, response validation, example selection, and CI integration makes Prism one of the most complete OpenAPI-native testing tools available.

Last updated on April 30, 2026.