Generate documentation

ApiWorkbench can turn your saved requests into documentation you can share. There are two exports: a Markdown file for one request and the response you just got, and a single page that documents a whole collection.

Export	Covers	Formats
Request doc	One request and its latest response	Markdown
Collection docs	Every folder and request in a collection	HTML or Markdown

Write descriptions first

Generated docs are more useful with a sentence or two about each part. Descriptions are optional, and are included wherever you add them.

For	Where to write it
A request	The request's Docs tab, in Description
A folder	Folder menu, Auth, scripts and docs, then the Docs tab
A collection	Collection menu, Auth, scripts and docs, then the Docs tab

Say what the request does and what it needs, for example "Creates an order. Needs a token from Login."

Document a whole collection

1. In the sidebar, open the collection's menu and select Generate docs….

2. In Export collection docs, choose a format:

   • HTML page: self-contained, opens in a browser.
   • Markdown: for READMEs and wikis.

3. Choose where to save the file. The suggested name comes from the collection, such as shop-api-docs.html or shop-api-docs.md.

A message confirms: "Docs saved (tokens and secret variables are masked)."

What the collection docs contain

For the collection, and for each folder:

• the description;
• the auth type that its requests inherit;
• the pre-request and post-response scripts, collapsed;
• for the collection, a table of its variables.

For each request:

• the method, name and URL;
• the description;
• path variables, query parameters and headers, as tables;
• the body;
• the auth type, and where it is inherited from;
• its scripts, collapsed;
• every saved example, with its status, response headers and response body.

Requests appear in collection order, grouped by folder. WebSocket, gRPC and other non-HTTP requests are included, with a badge showing their type. Long bodies are cut at 100 KB.

No-code tests and captures are not part of the generated docs.

HTML or Markdown?

	HTML page	Markdown
Opens in	Any browser	A text editor, or any site that renders Markdown
Styling	Built in, with light and dark colours	Up to where you publish it
Navigation	A table of contents and a coloured badge per method	A Contents list of links
Descriptions	Shown as plain text	Kept as written, so Markdown in them is rendered
Good for	Emailing, or hosting as a single file	A README, a wiki or a docs site

The HTML page is one file with nothing to load from the internet, so it can be attached to an email or opened offline.

Document one request with its response

This export captures a real exchange: what you sent and what came back.

1. Send the request, so a response is on screen.

2. In the response's status row, select the document icon. Its tooltip reads Save request and response as a Markdown doc (secrets masked).

   On a narrow window, open More response actions and select Save as Markdown doc.

3. Choose where to save the file. The suggested name is the request's name with .md, or request-doc.md for an unsaved request.

The Markdown file contains:

Section	Content
Title	The request's name, the method and URL, then the status, time and size
Request	Query parameters, headers, the body and an equivalent cURL command
Response	Response headers and the body. JSON is indented. Bodies are cut at 200 KB.
Footer	The date and time it was generated

The URL and values are written as you typed them, so {{variables}} stay as placeholders.

What is masked

Generated docs are meant to be shared, so credentials are replaced with ••••••:

• tokens and passwords from the Auth tab;
• the values of headers that carry credentials, such as Authorization and API key headers;
• the values of variables marked secret, wherever they appear.

In collection docs, a credential header keeps its scheme word, and a reference such as Bearer {{token}} stays readable because it holds no secret.

Check before you publish

Masking covers the places credentials normally live. It cannot recognise a secret typed directly into a URL, a query parameter, a body or a saved example, and it cannot mask personal data in response bodies. Read the file before you share it. Storing secrets in secret variables means they are masked everywhere.

Keep docs up to date

The exported file is a snapshot. When requests change, generate it again and replace the old file. To keep docs next to your code, export Markdown into the repository and commit it with the change.

Other ways to share a collection:

• Export it as an OpenAPI file, for tools that render API reference sites.
• Code snippets give a ready-to-run example of one request in many languages.

Next steps

• Collections: organise requests into folders.
• Export: share the collection itself.
• Console: see exactly what was sent.