Repository files navigation

Prism is a set of packages for API mocking and contract testing withOpenAPI v2 (formerly known as Swagger) andOpenAPI v3.x.

Prism provides:

• Mock Servers: Life-like mock servers from any API specification document.
• Validation Proxy: Contract Testing for API consumers and developers.
• Comprehensive API Specification Support: OpenAPI v3.1, OpenAPI v3.0, OpenAPI v2.0 (formerly Swagger) and Postman Collections.

Stoplight provides hosted mock servers for convenience so that API consumers can experiment with an API without the need for backend code.

Use one of these options for instant, hosted mock servers:

• Stoplight Platform: Collaborative API Design Platform for designing, developing and documenting APIs with hosted mocking powered by Prism.
• Stoplight Studio: Free visual OpenAPI designer that comes integrated with mocking powered by Prism.

Learn more in thehosted Prism documentation.

Prism is an open-source HTTP server run from the command-line. It provides mocking, request validation, and content negotiation. Use it standalone tool or in continuous integration.

This information refers to Open Source Prism 3.x, which is the current version most likely you will use. If you're looking for the 2.x version, look at the2.x branch

Prism requires

• NodeJS >= 18.20.1
• for NodeJS 18.x,>= 18.16 is required

npm install -g @stoplight/prism-cli# ORyarn global add @stoplight/prism-cli

For more installation options, see ourinstallation documentation.

Prism can help you create a fake "mock" based off an OpenAPI document, which helps people see how your API will work before you even have it built. Run it locally with theprism mock command to run your API on a HTTP server you can interact with.

prism mock https://raw.githack.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml

Learn more abouthow the mock server works.

Prism can help you check for discrepencies between your API implementation and the OpenAPI document that describes, letting you funnel HTTP traffic through it with theprism proxy command.

prism proxy examples/petstore.oas2.yaml https://petstore.swagger.io/v2

Learn more abouthow the validation proxy works.

• Documentation
  • Getting Started
  • Guides
• Community

Cannot access mock server when using Docker?

Prism uses localhost by default, which usually means 127.0.0.1. When using docker the mock server willbe unreachable outside of the container unless you run the mock command with-h 0.0.0.0.

Why am I getting 404 errors when I include my basePath?

OpenAPI v2.0 had a concept called "basePath", which was essentially part of the HTTP path the stuffafter host name and protocol, and before query string. Unlike the paths in yourpaths object, thisbasePath was applied to every single URL, so Prism v2.x used to do the same. In OpenAPI v3.0 theymerged the basePath concept in with the server.url, and Prism v3 has done the same.

We treat OAS2host + basePath the same as OAS3server.url, so we do not require them to go inthe URL. If you have a base path ofapi/v1 and your path is defined ashello, then a request tohttp://localhost:4010/hello would work, buthttp://localhost:4010/api/v1/hello will fail. Thisconfuses some, but the other way was confusing to others. Check the default output of Prism CLI tosee what URLs you have available.

• Content Negotiation
• Security Validation
• Validation Proxy
• Recording/Learning Mode (create OpenAPI from HTTP traffic)
• Data Persistence (allow Prism act like a sandbox)

Submit your ideas for new functionality on theStoplight Roadmap.

If you're using Prism for an interesting use case,contact us for a case study. We'll add it to a list here. Spread the goodness 🎉

If you are interested in contributing to Prism itself, check out ourcontributing docs ⇗ andcode of conduct ⇗ to get started.

Prism is built on top of lots of excellent packages, and here are a few we'd like to say a special thanks to.

• ajv
• faker
• fp-ts
• gavel
• json-schema-faker
• lerna
• micri
• openapi-sampler
• yargs

Check these projects out!

If you would like to thank us for creating Prism, we ask that youbuy the world a tree.