Publish API documentation and a changelog

Give a project's documentation and its changelog an address to share, by private link or public.

In short

A project's documentation page is built from its enabled requests, its API document and its saved examples; its changelog shows the versions a person verified. Publish them at one address, shared by private link or public. Secrets and values are never shown.

Before you start

• Who: publishing needs a confirmed email address and the right to manage the project.
• Plan: every plan. The pages end with the "Made with" line unless your organization hides it.
• First: enable the requests you want in the docs and save examples.

Steps

1. Open "Build", choose "Mocks, streams & docs", choose the project and open "Published docs" - or choose "Published docs" in the project's … menu on Requests.
2. Press "Preview the documentation" to see the page exactly as a reader gets it.
3. Switch on "Publish the API documentation", and "Publish the changelog" if you want it too.
4. Choose who can find it: "Anyone with the link" or "Public".
5. Press "Save", then "Copy link" and share it. You need a confirmed email address.

Result: the pages live at one address that cannot be guessed.

What a reader sees

Each request as an operation: its name, method, path without the server address, description, and the names of its parameters and headers - never their values. An id in a path is shown as a placeholder. The request body appears as a sample with variables left as written, and up to three saved examples per request. Secrets and sensitive fields are masked.

Never shown: environments, variable values, secrets, sign-in profiles, run history, or who works on the project. The changelog shows only verified versions, with their approved notes, and what is deprecated now.

Good to know

• "Anyone with the link": only people you give the link to can find the pages, and search engines are asked to stay away. "Public": anyone can open the pages and search engines may list them.
• Making pages public asks you to confirm what becomes public, every time something new would. Read the preview first.
• Switch a page off and save: the link shows nothing at once. "New link" replaces the address. "Remove" deletes the publication; its link is never used again.
• A reader can report a page from the link on it. Moderators can take pages down.
• The pages end with the "Made with" line unless your organization hides it. See /help/organizations/made-with-line.

If something goes wrong

• The preview is empty: the project has no enabled requests yet. "Mock the sandbox bookstore" in "Mock server" makes a project with something to show.
• The link shows nothing: the page is switched off, the link was replaced, or moderators took it down.

Related

• /help/api-testing/mock-servers
• /help/api-testing/api-changes
• /help/api-testing/verification-workflows