Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 30 ยท Organizing Work

Saved examples, documentation and mock servers

Save responses as Postman examples, publish generated API documentation, import OpenAPI files and run a mock server from examples. Includes a runnable mock stand-in.

A request tells you how to call an API. An example shows what comes back. Postman lets you save any response as an example attached to the request, and that small habit pays off three times: your colleagues see real, concrete answers, the generated documentation shows them to readers, and a mock server can serve them back as fake responses before the real backend even exists.

This lesson covers saved examples, Postman's documentation features, importing an OpenAPI description, and mock servers. Because the real Postman cannot run on this site, the GUI steps are read-only, and the mock server is demonstrated with a stand-in: a small Node server built from a list of examples, which is essentially what a mock server does.

One example, three uses

Saved example A request plus a response, stored.
Documentation Readers see real answers.
Mock server Examples become fake endpoints.

Write each example once and reuse it everywhere.

1 / 2

Saving a response as an example

Send a request. In the response area, click Save Response (or Save as example, depending on your version). Postman stores a copy of the request and the response as an example under the request in the sidebar. You can then rename it and edit everything: status code, headers and body.

Good examples cover more than the happy path. For GET /orders/{id} create:

  • 200 OK: an existing order
  • 404 Not Found: unknown id
  • 401 Unauthorized: missing token

For each example, give a descriptive name (Order found, Order not found) and fix any data that would look strange to a reader (replace real names and emails with obviously fake ones). Edited examples do not need to come from a real call at all: you can create an example by hand to describe an answer the API should give.

Documentation

Postman can generate documentation straight from your collection. Open a collection and its Overview or Documentation tab: the Markdown descriptions of the collection, folders and requests are shown as pages, the requests list parameters, headers and body, and saved examples appear as sample responses beside them. Many versions can also render code snippets for the request in languages such as cURL, JavaScript and Python.

You can keep the documentation private inside the workspace or publish it to a web page that anyone with the link can read. Before publishing, check:

  1. Every request has a description with the purpose and required fields.
  2. Examples exist for success and for the main errors.
  3. No example, variable or header contains a real secret or personal data.

The documentation stays in sync with the collection, so updating a request or an example updates the page. That is its main advantage over a hand-written wiki, which rots.

Importing an OpenAPI description

If your API already has an OpenAPI file (a YAML or JSON description of endpoints, parameters and response shapes; see Contract testing and OpenAPI), you do not have to build requests by hand. Use Import and choose the file. Postman creates a collection with one request per operation, folders based on tags or paths, and often examples taken from the file's examples or response schemas.

A tiny excerpt of what such a file looks like:

YAML
openapi: 3.0.3
info:
  title: Shop API
  version: "1.0"
paths:
  /orders/{id}:
    get:
      summary: Get one order
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: The order
        "404":
          description: Unknown order

Treat an import as a starting point. Review the generated requests, add variables for the base URL, and write tests (see Writing tests with pm.test and Chai).

Mock servers

A mock server is a fake API hosted by Postman. You create it from a collection (the Mock option in the collection menu) and choose whether it should be public or private. Postman gives you a base URL. When a request arrives, the mock looks for a saved example whose method and path match and returns that example's status, headers and body. Optional request headers, as described in the Postman documentation for your version, can ask the mock for a particular example by name or status code, which is how you force an error on demand.

Typical uses:

  • A frontend developer builds against the mock while the backend is written.
  • A test suite checks how a client handles a 500 or an empty list without breaking a real service.
  • A workshop or demo needs predictable data with no network dependency.

Mocks are only as good as their examples. If the real API changes and the examples do not, the mock lies, and tests pass against something that no longer exists. Pair mocks with contract checks.

A stand-in mock server

The real Postman mock server is a hosted service, so it cannot run here. This stand-in does the same job in a few lines of Node: it takes saved examples (each with a method, path, status and body), starts an HTTP server on loopback and answers matching requests. It then calls itself with fetch, including a request that matches no example.

Node.js Build a mock server from saved examples

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The last call shows the most important failure mode of any mock: a request for something nobody saved an example for. A good mock reports that clearly instead of inventing an answer.

Documentation generated from examples

The same list of examples can be turned into readable documentation. This second stand-in prints a Markdown-style page for each request, the way a documentation tool lists a request with its sample responses.

JS Generate documentation text from examples

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Habits that keep these features useful

  • Save an example for every status code a client must handle, not just 200.
  • Use fake, obviously safe data in examples.
  • Keep examples in step with the real API: update them whenever a response changes.
  • Mark mock servers as private unless the whole world should call them.
  • Do not put anything sensitive in documentation you plan to publish.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a Postman mock server return for an incoming request?

    A mock looks up a saved example by method and path and replies with that example's status, headers and body.
  2. 2. Why is it risky to rely on a mock whose examples are never updated?

    A mock only knows what its examples say. If the real API drifts, the mock becomes a comforting lie.
  3. 3. You import an OpenAPI file into Postman. What do you get?

    The import creates requests (and sometimes examples). Variables, tests and review are still your job.
  4. 4. Which examples should a request like GET /orders/{id} ideally have?

    Clients must handle errors too, so documentation and mocks should show the main failure responses, not only success.

Summary

  • A saved example stores a request with a response; create them for success and error cases.
  • Documentation is generated from descriptions and examples, and can be kept private or published; check for secrets first.
  • Importing OpenAPI gives you a starting collection, not finished tests.
  • A mock server matches incoming requests to examples; it is only as accurate as those examples.
  • The Node stand-in shows the matching logic, including the "no example found" case.

Next: start scripting with Pre-request scripts.