Postman API Documentation

Postman generates API documentation directly from your collections. Instead of writing a separate document in Word or Google Docs, you add descriptions to your requests inside Postman and publish the documentation to a live, shareable webpage — automatically formatted and always up to date.

Why Documentation Matters

A well-documented API saves everyone time. Developers do not have to guess what an endpoint does, what parameters it expects, or what the response looks like. Good documentation is the difference between an API that gets adopted quickly and one that causes endless back-and-forth questions.

Where Postman Pulls Documentation From

Collection name and description    →  Page title and intro
Folder names and descriptions      →  Section headings
Request names                      →  Endpoint titles
Request descriptions               →  Endpoint explanations
Saved examples                     →  Code samples and sample responses
Parameter descriptions             →  Parameter reference table

Every description you add inside Postman becomes a part of the published documentation page.

Add a Description to a Request

1. Click a request in your collection to open it
2. Click the small edit icon or the field that says "Add a description" below the request name at the top of the request tab
3. Type your description using plain text or Markdown
4. Press Save

Good Request Description Example

## Get User by ID

Returns a single user object. The user is identified by their numeric ID
passed in the URL path.

**Required permissions:** None (public endpoint)

**Rate limit:** 1000 requests per hour per API key

Add Descriptions to Parameters

1. Open a request and go to the Params tab
2. Click in the Description column next to any parameter row
3. Type a short description of what this parameter does

The documentation page displays this as a table under the endpoint, explaining each parameter to the reader.

Publish Documentation

1. Click your collection name in the sidebar
2. Click the three-dot menu and select View Documentation
3. The documentation preview opens in a browser-style panel inside Postman
4. Click the Publish button in the top-right corner
5. Choose who can see it: private team, or public on the internet
6. Click Publish Collection

Postman generates a public URL like https://documenter.getpostman.com/view/123456/your-collection. Share this link with anyone.

What the Published Documentation Page Looks Like

┌──────────────────────────────────────────────────┐
│  Online Store API Documentation                  │
│  Base URL: https://api.store.com/v1              │
│                                                  │
│  ▸ Authentication                                │
│      POST /auth/login                            │
│      POST /auth/refresh                          │
│                                                  │
│  ▸ Products                                      │
│      GET  /products          → Get all products  │
│      GET  /products/{id}     → Get one product   │
│      POST /products          → Create product    │
│                                                  │
│  [ Try It in Postman ] button on each endpoint   │
│  [ Run in Postman    ] button at the top         │
└──────────────────────────────────────────────────┘

Each endpoint shows its method, URL, description, parameters, and a sample response from your saved examples.

Run in Postman Button

The published documentation page includes a Run in Postman button. Visitors click it to import your entire collection into their own Postman workspace in one click. This is extremely useful for onboarding new API users or sharing a testing suite with your team.

Use Markdown in Descriptions

Postman descriptions support Markdown formatting. This means you can structure them with headings, lists, code blocks, and emphasis:

**Required Parameters**
- `userId` (integer) – The ID of the user to retrieve

**Example Response**
```json
{
  "id": 1,
  "name": "Alice Park"
}
```

**Notes**
Returns a 404 if the user does not exist.

Add a Collection Description

1. Click your collection name in the sidebar
2. Click the edit (pencil) icon next to the name or the description area
3. Write an overview of the API — what it does, who it is for, and the base URL
4. Click Save

This description becomes the introduction section on the published documentation page.

Keep Documentation Up to Date

Every time you update a request description or add a new saved example, the documentation updates automatically after you republish. Postman documentation stays in sync with your collection because it reads directly from it.

Documentation and Environments

When you publish documentation, you can select a specific environment to use as the base for the shown URLs. This lets you publish documentation showing your production base URL while you test locally with a different environment active.

Summary

Postman generates live documentation from your collection's descriptions, parameter notes, and saved examples. Add Markdown descriptions to requests, folders, and the collection itself. Publish with one click to create a shareable URL. The Run in Postman button lets anyone import your collection directly. Documentation stays current because it reads from your collection each time you publish.