Skip to main content
The specification editor is a text editor for your OpenAPI document, with three things wrapped around it: an outline of the document in the sidebar, a documentation preview beside it, and problems flagged on the lines that caused them.

​
Prerequisites

  • A project is open. Specifications belong to a project, so there is nowhere to put one until you have picked a project.
  • Your role can edit. On a read-only role the editor opens, but it will not accept typing and Save is disabled with the reason on hover.

​
Create a specification

1

Start a new specification

In the API Client sidebar, open API Design and click the + on the Specs header. Choose OpenAPI 3.1 (default) or OpenAPI 3.0.You can also use + New → API spec from the sidebar toolbar, which offers the same two versions.
2

Name it

The document opens in a new tab with the name in the breadcrumb focused. Type a name and press Enter. You can rename it later by clicking the name in the breadcrumb.
3

Write the document

A new specification is seeded with a minimal valid document so the editor is never a blank page:
Fill in info, then add servers, paths, and operations.
4

Save

Press Cmd/Ctrl + S, or click Save in the tab header. A • unsaved marker sits next to the name until you do.
Once saved, the specification appears under Specs in the sidebar and expands into an outline of what you wrote.

​
The editor at a glance

The specification editor with the document outline in the sidebar, the OpenAPI document in the middle, the documentation preview on the right, and the issues panel docked belowThe specification editor with the document outline in the sidebar, the OpenAPI document in the middle, the documentation preview on the right, and the issues panel docked below
Four regions, all working on the same document:
  • The outline, in the sidebar under the specification’s name. The document’s structure as a tree.
  • The document, in the middle. Where you type.
  • The Documentation rail, on the right. A rendered preview of whatever you are looking at.
  • The Issues panel, below the editor. Everything currently wrong with the document. It can be docked to the bottom or the right, or collapsed out of the way. See issues and governance.
Drag the divider between the document and the rail to give either one more room.

​
The toolbar

Above the document:
  • Back and forward arrows. These walk your navigation history inside the document, so after following a $ref or clicking an outline row you can return to the exact line you left.
  • The OpenAPI version of the specification, as a label. It is not a switcher.
  • A YAML / JSON dropdown. Picking the other format converts the document in place.
  • Two icon buttons on the right: Copy code copies the whole document, and Prettify code runs Prettier over it, in YAML as well as JSON.
Long lines are not wrapped. OpenAPI nests deeply, and wrapping breaks the indentation you are reading structure from, so the document scrolls sideways instead.
Converting YAML to JSON drops every comment in the document, because JSON has none. Converting back gives you valid YAML but not your original formatting, and YAML anchors and merge keys do not survive: a merge key is flattened and left behind as a literal << property. If the conversion fails because the document does not parse, Requestly tells you why and leaves the document untouched.

​
Write with help from the editor

As you type inside the document, Requestly offers completions for the OpenAPI keys and values that are valid at the cursor, drawn from the OpenAPI 3.1 schema. HTTP methods and enum values are ranked above generic keys, so inside a path item the methods come first. Hover a key to read what it means. Problems appear as you introduce them: a YAML or JSON syntax error, a structural violation, a broken reference, or a governance rule your project enforces. Each is underlined on the offending line and listed in the Issues panel.

​
Add a section from the outline

The outline always shows the five top-level buckets, Servers, Tags, Paths, Components, and Security, even when the document has none of them yet. Empty ones read “No servers yet” and the like. Security is not populated yet, so it reads empty even once your document declares security requirements. Hovering Servers, Tags, or Paths reveals a +. Click it and Requestly splices a starter entry into that block and scrolls the editor to it, ready for you to edit. On Components the + opens a submenu first, so you pick which component category the new entry goes into.
Section insertion writes YAML. On a document stored as JSON the + does nothing rather than reformat your file, so switch to YAML first if you want it.

​
Move between the outline and the document

The outline and the cursor stay in step, in both directions.
  • Click an outline row and the editor scrolls to that node and puts the cursor at its first line. Clicking the same row again scrolls back to it.
  • Move the cursor in the document and the outline highlights the row you are now inside, and expands to reveal it.
Either way, the Documentation rail follows: land inside an operation and the rail renders that operation, land inside a component and it renders that component, click the specification’s own name and the rail returns to the overview.

​
Reference a component with $ref

Type $ref: followed by the first letters of the component’s name, and Requestly offers every component you can point at, narrowing the list as you type. Two kinds appear in the same list, labelled in the right-hand column:
  • in-spec, the components defined inside this document under components:. Selecting one inserts a JSON pointer such as '#/components/schemas/Error'.
  • library, the project’s shared Component Library entries. Selecting one inserts the path to that entry, such as '../../components/schemas/Pet.yaml'.
The $ref autocomplete open in the specification editor, listing in-spec and library components with their category in the detail columnThe $ref autocomplete open in the specification editor, listing in-spec and library components with their category in the detail column
Completion fires where $ref looks like a key at the start of the line, so a $ref mentioned mid-sentence in a description does not trigger it.

​
Reading and following a reference

A reference into the Component Library is drawn as a chip showing the entry’s name and category, rather than the raw file path, so you can skim what a document points at. Hover the chip for the target’s description and a preview of its body.
Hovering a $ref chip in the specification editor shows the referenced component's category, name, description, and a preview of its bodyHovering a $ref chip in the specification editor shows the referenced component's category, name, description, and a preview of its body
Cmd/Ctrl + click a reference to follow it:
  • A library reference opens that component in its own tab.
  • An in-spec reference scrolls this document to the definition.
In-spec references stay as plain text rather than becoming chips. #/components/schemas/Error is already short and tells you where the definition lives, and hiding it behind a chip would take that away. Either way, the toolbar’s back arrow returns you to the line you followed the reference from.

​
Read the documentation preview

The rail on the right renders the current selection as documentation: the operation’s parameters, request body, and per-status responses, or a component’s schema as an expandable tree. References inside the rail are resolved and expanded in place, so you read the real shape instead of a pointer. The rail is a preview, not a second editor. Clicking around in it never changes what the document says.
The Documentation rail rendering a single operation with its path parameter and its response schema treeThe Documentation rail rendering a single operation with its path parameter and its response schema tree
The rail also carries a Versions tab for the specification’s releases, and on any cloud project a Changelog tab recording every save. Both are covered in versions and releases.

​
Rename or delete a specification

Both live on the specification’s row in the sidebar, under the ⋯ menu, and renaming is also available by clicking the name in the breadcrumb. A rename changes the specification’s name in Requestly and, in a local project, the file it is stored in. It does not rewrite info.title inside the document, so update that yourself if you want the two to match. Deleting asks for confirmation first and cannot be undone.