Skip to main content
A collection that is linked to an OpenAPI specification can publish that specification as a documentation site. Requestly hosts the result at a fixed URL, and the reader opens it in a browser without installing anything. Public and password-protected docs need no Requestly account. Internal docs are the exception: they ask the reader to sign in as a member of the project. What gets published is always a released version of the specification, never your working document. You pick which release goes live, and it stays live until you pick a different one.

​
Before you publish

  • A cloud project. Publishing is not available in local projects. In one, the collection’s Documentation tab reads “Publishing is not available in local projects” and offers no publish control.
  • A top-level collection. The collection’s Documentation tab appears on root collections only, not on folders inside them.
  • A linked specification. If the collection has none, you can generate one from the collection itself.
  • At least one released version of that specification. Until one exists, Publish stays disabled. See versions and releases.
  • Edit access to the collection. Without it, Publish and Unpublish stay disabled and their tooltips say you need edit access.

​
Publish a collection’s documentation

1

Open the collection's Documentation tab

Select the collection in the sidebar, then open the Documentation tab in the tab strip beside Overview, Variables, Authorization, Scripts and Runner.A Synced from spec line at the top carries a Go to source link. The link opens the specification the docs come from, and only its tooltip names that specification. Once the docs are live, this line disappears. The same link then sits in the top-right of the status card.
2

Choose who can read the docs

Pick one of the three Visibility options. They are covered in detail under visibility modes.
The Documentation tab of a collection showing the Public, Internal and Password visibility options, the Spec version dropdown and the Publish buttonThe Documentation tab of a collection showing the Public, Internal and Password visibility options, the Spec version dropdown and the Publish button
3

Pick the version to serve

Open the Spec version dropdown and choose a released version. Each entry shows its name and release date, and the one currently live is marked (currently live).A version released without scrubbing carries a warning icon, and selecting it shows: “This version was released without scrubbing - its content, including any credentials, will be visible to anyone who can access this documentation.” Release a scrubbed version instead if that matters to you.
4

Publish

Click Publish. The docs go live immediately and a status card appears above the form.
5

Share the URL

The status card shows a Live badge and the documentation URL, which has the form <your Requestly URL>/view/<project-id>/<collection-id>. Use the copy button to put it on your clipboard, or View to open the published page in a new tab.
The published status card with a Live badge, the documentation URL with a copy button, a View button, the current visibility and version, and Republish and Unpublish buttonsThe published status card with a Live badge, the documentation URL with a copy button, a View button, the current visibility and version, and Republish and Unpublish buttons
The URL is derived from the project and collection, so it never changes. Republishing a different version reuses the same link, and every bookmark your readers made keeps working.
A published collection also carries a small green checked-clipboard icon in the sidebar, with a Published tooltip, so you can tell at a glance which collections are live.

​
Visibility modes

​
Set a password

Choose Password and the form reveals a password field. The password must be 8 to 128 characters. There are no composition rules, so a passphrase is fine. The password is never stored in a form you can read back. When you republish a collection that is already password-protected, leaving the field blank keeps the current password, and typing a new one replaces it.
Everything in the released version reaches everyone who can open the docs. A password gates the page, not the contents of the snapshot.

​
Publish from a collection with no specification

A collection that was never linked to a specification shows an empty state reading “Not linked to an API spec yet”. You have two ways forward from here.
The Documentation tab empty state reading Not linked to an API spec yet, with Open API Design and Generate spec from this collection buttonsThe Documentation tab empty state reading Not linked to an API spec yet, with Open API Design and Generate spec from this collection buttons
  • Open API Design takes you to the specification editor, where you write a document and generate its collection.
  • Generate spec from this collection builds an OpenAPI specification out of the requests you already have, in one step.
Generate spec from this collection is disabled when the collection holds no HTTP requests at all. Its tooltip explains why: only HTTP requests can be described by an OpenAPI specification.

​
Generate a specification from the collection

Click Generate spec from this collection, give the specification a title, and confirm with Generate spec.
The Generate spec from this collection dialog with a Spec title field, an explanation of the one-way sync, and a warning listing what will not be in the specThe Generate spec from this collection dialog with a Spec title field, an explanation of the one-way sync, and a warning listing what will not be in the spec
The dialog counts the HTTP requests it will convert and states the consequence plainly: the generated specification becomes the source of truth. From that point on, edits flow one way. Changes you make in the specification reach the collection when you run Update Collections, and changes you make in the collection do not flow back. Under the heading “Some of this collection won’t be in the spec”, the dialog lists only what you would lose. The block is absent when nothing is lost, and each kind below appears only when your collection holds it:
  • Non-HTTP requests. GraphQL, gRPC, MQTT, WebSocket and Socket.IO requests are skipped, because OpenAPI cannot describe them. Each kind is counted so you know what you are leaving behind.
  • Folders, which flatten into paths.
  • Saved examples, which are not carried over.
  • Pre-request and test scripts, which are not carried over.
Once the specification exists, release a version of it and come back to the Documentation tab to publish.

​
Keep the published docs current

The live version never changes on its own. Releasing a new version of the specification does not move the docs onto it, so a reader is never surprised by a document you were not ready to ship. Requestly tells you when the two have drifted apart:
  • A newer release exists. The status card reads “Newer spec release available”, names the newest version, and asks you to select it below and republish.
  • You changed the form but did not apply it. The card reads “You have unpublished changes to the version or visibility”, which is the reminder to click Republish.
To move the docs forward, select the version you want in Spec version, adjust visibility if you need to, and click Republish. The URL is unchanged.
The specification editor tracks this from the other side. Its Versions tab has a Published as docs section listing every collection publishing from that specification and whether each one is Current or Newer available. See versions and releases.

​
Unpublish

Click Unpublish beside the primary action and confirm in the dialog titled “Unpublish this collection’s docs?”. The dialog states the outcome: “Visitors will see a 404 until you re-publish. Your visibility and version settings are kept.” The 404 is the response the page requests; what a visitor actually reads is the “Documentation unavailable” page described under when a reader cannot open the docs. Confirming with Unpublish takes the page down; Keep published backs out and changes nothing. Because the settings survive, republishing later is a single click - you do not have to pick the version and the visibility again.
Deleting the collection, or deleting the released version the docs point at, also takes the published page down. The delete confirmation for a version names every collection that will be unpublished.

​
What a recipient sees

The published page is a standalone reader. It has no Requestly application chrome, no sidebar of your other collections, and nothing editable. It shows the outline of the API on the left and the rendered document on the right.
The published documentation reader with the endpoint outline grouped by tag on the left and an operation with its parameters, responses and code samples on the rightThe published documentation reader with the endpoint outline grouped by tag on the left and an operation with its parameters, responses and code samples on the right

​
Finding an endpoint

  • Endpoints are grouped by tag. The outline lists one group per tag from your specification, with each operation under it carrying its method badge. A specification that declares x-tagGroups nests its tag groups under those super-groups. A specification with no tags falls back to a single flat Paths group. A Servers group sits above the tag groups and a Components group below them.
  • Search the outline with Cmd/Ctrl + K. The shortcut jumps straight to the outline’s search field, which filters the tree as the reader types.
  • The outline follows the reading position. Scrolling the document highlights the matching outline row, so a reader deep in a long document always knows where they are.
Every operation has its own URL. As a reader moves through the document, the address bar updates with a fragment naming the current section, so copying the URL at any point links to exactly that operation. Opening such a URL scrolls straight there instead of to the top of the page. The fragment is derived from the specification, so it is readable and stable:
Component schemas use the same idea, with fragments of the form #components.schemas.User.

​
Copy a request in six languages

Each operation carries a code sample panel with cURL, JavaScript, Python, Go, Java and Ruby tabs. Pick a language, click Copy, and the snippet is on the clipboard. The samples are there to be copied and run elsewhere; the reader does not send requests. A request body larger than 50 KB is trimmed in the sample, and the panel says so beneath the snippet.

​
Open the specification as .md or .json

The reader’s header has .md and .json buttons. Each one opens the released specification in that format in a new tab, so a reader can feed it to another tool or keep a copy.

​
How the document is rendered

The reader renders the document faithfully rather than summarising it:
  • Markdown is rendered. Descriptions on the API itself, on tags, on operations, on components and on individual schema properties all render as formatted text, so code spans, bold text and links appear as you wrote them.
  • oneOf and anyOf are labelled. A schema built from alternatives shows each branch under a clear heading instead of collapsing them together. Where the specification declares a discriminator, the reader shows a variant selector and narrows the schema to the type the reader picks.

​
When a reader cannot open the docs

A reader who cannot open the docs gets a page that says why, as far as it is safe to say so:
  • Password docs show a prompt reading “This documentation is password-protected”. A wrong password returns a plain “Incorrect password.” with no hint.
  • Internal docs send a signed-out visitor to sign in first. A signed-in visitor who is not a member of the project is told they do not have access and to ask the project owner.
  • An unpublished, deleted or mistyped link shows an outside visitor the same “Documentation unavailable” page in every case. The page does not reveal whether the docs ever existed, so the URL cannot be used to probe for collections. A signed-in member of the owning project is the one exception. That page tells the member the docs are unpublished, and offers an Open in Requestly button to go and republish them.

​
Next steps