Documenting requests
Describe what a request does with a summary, Markdown notes and reference links.
Overview
The Documentation tab keeps notes with a request: a one-line summary, details written in Markdown, an operation ID and tags, and a link to external documentation. Documentation is saved with the request and never changes what it sends.
When you import an OpenAPI spec, Relay fills in each request's documentation from its operation. A Postman import brings each request's description into Details.
Write documentation
- In the request editor, click Documentation, or press Command-1.
- Click Edit at the top of the tab.
- Fill in the fields you need.
The form has three sections:
- Description: Summary is a short line about what the request does. Details holds longer notes in Markdown.
- Reference: Operation ID is the operation's identifier, such as
listPets. Tags groups the request with others; separate tags with commas. Turn on Mark as Deprecated to flag a request that shouldn't be used anymore. - External Documentation: URL links to documentation elsewhere, and Title is the link's text. Without a title, the link shows the URL.
Read documentation
Click Preview at the top of the tab. The preview shows the summary as a heading, crossed out if the request is deprecated, followed by a Deprecated tag, the operation ID and the tags, then the details and the external link. Variables in the documentation show their current values, as they would when the request is sent.
A request that has documentation opens its Documentation tab in Preview. One without any opens in Edit.
Format details with Markdown
Details supports the Markdown that API descriptions use most:
- Headings, written with
#or underlined with=or-. - Paragraphs, with bold, italic, inline code and links.
- Bulleted, numbered and task lists, which can be nested.
- Block quotes.
- Code blocks, fenced or indented.
- Tables, written with pipes.
- Horizontal rules.
Anything else appears as plain paragraph text. Links open in your default browser.
See Also
- Importing OpenAPI specs: Create a collection of requests from an OpenAPI 3.0 or 3.1 spec.
- Importing Postman collections and environments: Bring Postman collections, with their folders, auth and scripts, and Postman environments into Relay.
- Creating and managing requests: Keep requests as drafts or save them in collections, and rename, duplicate and open them in their own windows.