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

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.
  • Copy and Format, on the right. Format runs Prettier over the document, 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. 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. 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'.
Completion only fires where $ref is a real key on the line, so a $ref mentioned inside a description string never triggers 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.
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 rail also carries a Versions tab for the specification’s releases, and on a team 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.