API Documentation in Postman

A Postman collection is half a documentation set already. It has the URLs, the methods, the headers, the request bodies, and (if you've followed Chapter 4) saved example responses. Postman generates a browsable, shareable docs site out of all of that — automatically, kept in sync with the collection. This lesson covers how to write descriptions that turn a collection into proper docs, how to publish them, and why even a QA team that doesn't own the API benefits from documenting their test collection.

What "auto-generated docs" actually means

Open any collection → click the View Documentation icon (or right-click → View Documentation). Postman renders a docs page with:

• The collection's name and description as a header.
• Every folder as a section, with its description.
• Every request as a sub-section showing method, URL, parameters, headers, body, and any saved examples.
• Markdown-rendered descriptions throughout.

Nothing was generated separately. Postman walks the collection's structure and renders it. Update the collection → the docs update. It's the cheapest documentation-in-sync-with-source-of-truth setup most teams will ever achieve.

Adding descriptions that are worth reading

A collection without descriptions makes mediocre docs. The work is writing them. Three places to add description text:

Collection description

Right-click the collection → Edit → the right-side description panel. This is the doc's front page. A good one answers in a few paragraphs:

• What does this collection cover (which API, which environment)?
• Who's the intended reader?
• How do you set up to run it (which environment to import, which secrets to populate)?
• Where does the source of truth live (Git repo, OpenAPI spec, owning team)?

A reasonable template:

# JSONPlaceholder API Tests
 
This collection contains API tests for the JSONPlaceholder REST API.
It demonstrates CRUD lifecycle testing, data-driven runs, and chained
authentication patterns.
 
## Running locally
 
1. Import this collection.
2. Import the **JSONPlaceholder** environment.
3. Set the active environment to JSONPlaceholder.
4. Run the **Smoke** folder to confirm setup is correct.
 
## Owners
 
QA team. Source of truth is in Git: `tests/api/postman/`.

Markdown renders properly — headings, lists, code blocks, tables. Don't go overboard; a focused page beats a sprawling one.

Folder description

Right-click any folder → Edit → description panel. Use these for "what does this folder cover?"

## Smoke
 
Five fast read-only requests against the public API. Run these first.
Total runtime: under 5 seconds. No auth required.

Request description

On any request, click the request name at the top. A description editor appears underneath. Use it for:

• What this request tests.
• Any side effects ("this actually charges the test card").
• Special handling required ("requires admin role").
• Linked references — Jira tickets, Swagger entries, ADR docs.

## POST Create Post
 
Creates a new post under a given user.
 
- **Side effect:** None on JSONPlaceholder (fake API).
- **Auth required:** No.
- **Notes:** The returned `id` is always 101 — JSONPlaceholder is a mock and doesn't persist.

The descriptions live alongside the requests. They become the docs. They also become the comments that show up in pull requests when teammates review the collection (Chapter 2 Lesson 4).

Saved examples — the docs killer feature

A docs page that says "this endpoint returns a user object" is fine. A docs page that says "this endpoint returns this exact JSON" with a clickable example is far more useful.

Postman uses saved examples (Chapter 4 Lesson 4) directly in the docs. Each example becomes a tab on the request's docs section. If you've saved 200 — Success, 404 — Not Found, and 400 — Validation Error examples on a request, the docs show all three with their full bodies, headers, and status codes.

The setup is identical to the mock-server lesson: send the request → Save Response → Save as Example → name descriptively. Examples earn double-duty: they power mock servers and power the docs.

Publishing the docs

The docs are private to your workspace by default. To share them outside it:

Once published, every change to the collection updates the public docs within seconds. There's no separate build or deploy step — the published docs are a live view of the collection.

Why QA teams should document test collections, not just APIs

A common confusion: "we don't own the API, so why document anything?" The collection you're publishing isn't necessarily the API spec — it's your test suite, and that has its own audience:

• New testers joining the team. A documented collection with descriptions on each test scenario is a faster onboarding path than reading 200 JS scripts cold.
• Developers triaging a failed run. A request whose description says "tests the duplicate-email rejection flow" is faster to diagnose than one called Test 14.
• Product managers and stakeholders. They'll never run Newman, but they can read a docs page that explains "we test these 30 scenarios on every PR."
• Auditors and compliance. Documented test coverage is its own compliance artefact in regulated industries.

The published docs become the front door of your test suite. Free. Auto-updating.

Generating proper API docs from an OpenAPI spec

If you do own the API and want production-grade API documentation, the workflow is:

1. Maintain the OpenAPI spec as the source of truth (Swagger, Stoplight, hand-written YAML).
2. Import the spec into Postman → it becomes a collection (Chapter 2 Lesson 3).
3. Postman's auto-docs of that collection are essentially OpenAPI rendered through Postman's lens.
4. Re-import on spec changes; docs stay in sync.

For most API providers a dedicated docs renderer (Stoplight, ReadMe, Redoc) is the better long-term answer. Postman's docs are great for test collections and for internal APIs where the collection is the spec.

Markdown features worth knowing

Postman's markdown supports:

• Headings (#, ##, ###) — for sections within a description.
• Lists (-, 1.) — for ordered or unordered lists.
• Inline code (`pm.test()`) and code blocks (triple-backtick, optionally with a language).
• Tables — pipe-delimited.
• Links — [text](url).
• Images — ![alt](url).
• Blockquotes — >.

It does not support: HTML embedding, custom CSS, or interactive widgets (other than the example tabs Postman ships).

A description that uses several features:

## GET User by ID
 
Returns a single user by their numeric id.
 
**Parameters**
 
| Name | In | Required | Description |
|------|-----|----------|-------------|
| id   | path | yes | User id (numeric, 1-10 on JSONPlaceholder) |
 
**Response codes**
 
- `200` — user found
- `404` — user not found (real API; JSONPlaceholder returns 200 + `{}`)
 
> ⚠️ Heads up: this endpoint is rate-limited to 100 requests per minute on production.
 
See also: [GET All Users](#get-all-users), [Auth setup](https://internal.wiki/auth).

That's a real, useful piece of docs. Five minutes per request to write; pays back many times over the lifetime of the suite.

⚠️ Common mistakes

• Letting descriptions go stale. A docs page that's wrong is worse than no page. Add a "last reviewed" date to the collection description and review quarterly.
• Documenting what code already shows. "This is a GET request" is not a description — Postman shows the method already. Describe why, side effects, and gotchas; let the request itself describe the what.
• Publishing docs that contain real secrets. If your descriptions or saved examples include real tokens or production data, anyone with the public URL has them. Sanitise before publishing — {{authToken}} placeholders, fake test data only.

🎯 Practice task

Document your collection. 25-30 minutes.

1. Open JSONPlaceholder API Tests → right-click → Edit → description panel. Paste a 4-paragraph description following the template above (purpose, how to run, owners, source of truth).
2. For each folder (Users, Posts, Comments, CRUD Chain), add a one-paragraph description explaining what's in it.
3. Pick three requests. For each, click the request name and write a short description that covers what it tests, any side effects, and any gotchas.
4. Save examples. On GET User by ID, save three examples: 200 OK — Single User (the real response), 404 Not Found — Synthetic (a manual one for /users/9999), and 400 Bad Request — Synthetic (manual: invalid id format).
5. Open View Documentation (right-click collection → View Documentation). Browse the rendered docs. Click between the example tabs you saved. Note that everything you wrote in markdown renders correctly.
6. Publish. Click Publish in the docs view. Choose private/team-only (don't make this public — it's just a learning exercise). Postman gives you a URL. Open it in a private browser window — that's what teammates would see.
7. Stretch: add a markdown table to one request's description listing all the query parameters with their types and defaults. Open the docs view to confirm the table renders. Now your docs include parameter reference, not just example bodies.

You can now turn any Postman collection into shareable documentation. The last lesson of this chapter zooms out one more level: how teams actually collaborate around shared collections, with workspaces, forks, pull requests, and scheduled monitoring.