Create OpenAPI mock server

Creating a mock server from a Swagger/OpenAPI file is a powerful way to decouple front-end and back-end development. It allows front-end developers to start building and testing their applications against a realistic API without waiting for the back-end to be completed.

Here's a step-by-step guide on how to set up a simple mock server using your OpenAPI specification file.

Step 1: Install the Mock Server Tool

There are many tools available for creating mock servers, but one of the most popular and easiest to use is Prism by Stoplight. It’s a powerful CLI tool that can generate a mock server directly from your OpenAPI file.

Install Prism globally using npm:

npm install -g @stoplight/prism-cli

---

Step 2: Prepare Your OpenAPI Specification

Before you can mock your API, you need to ensure your OpenAPI file is ready. For a mock server to return a meaningful response, your specification must contain an example response for each endpoint.

In your YAML or JSON file, go to the paths section and define an example within the responses block for each HTTP method.

Example for OpenAPI 3.0:

paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
              example: # This is the key part for mocking
                - id: 1
                  name: John Doe
                  email: john.doe@example.com
                - id: 2
                  name: Jane Smith
                  email: jane.smith@example.com

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

Without the example field, Prism will try to generate a response based on the schema, but it won't be as precise or useful.

---

Step 3: Run the Mock Server

Once your specification is ready and saved (e.g., as openapi.yaml), you can start the mock server with a single command.

The prism mock command starts an HTTP server that uses your OpenAPI file to define the API behavior.

prism mock openapi.yaml

By default, Prism will start the server on http://localhost:4010.

Now, when you send a GET request to http://localhost:4010/users, the server will return the predefined JSON from the example field in your specification.

Step 4: Advanced Features

Prism can do more than just return static examples. It can:

• Validate Requests: It will check if incoming requests match the schema defined in your OpenAPI file.
• Handle Different Status Codes: If you define examples for different response codes (e.g., 404, 500), you can get those responses by using the __code query parameter in your request. http://localhost:4010/users?__code=404 will return the 404 response.
• Randomize Responses: If you omit the example field, Prism can generate random data that conforms to your schema, which is useful for testing validation on the client side.

---

Summary

Creating a mock server from your OpenAPI specification is a streamlined process that allows for parallel development. By adding example responses to your API reference and using a tool like Prism, you can quickly set up a powerful and realistic mock environment. This frees up your development team to work independently and reduces dependencies, speeding up the development cycle.