The OpenAPI editor
The editor you paste an OpenAPI description into: what each part does, what happens to references to other files, and how to undo a change.
The editor, part by part
- Examples: five small descriptions to start from or learn from.
- Colours: Auto (match Confluence), Light or Dark. See Colours and dark mode.
-
Diagram source: the description. Keys, strings,
numbers, comments and
$refare colored, to make it easier to read. - Preview: the map as it will look, redrawn as you type.
- Size on the page, under the preview: Readable (automatic) suits most APIs. It never enlarges a small map. A wide one is shrunk to fit, but to three quarters of its size at most; a wider one scrolls sideways. Fill the width stretches or shrinks it to the page width. Actual size shows it as drawn.
- Syntax reference, under the editor: what the map shows, the parts at the top of a description, references, and formats.
- Save, Revert changes and Cancel, at the foot. See Undo a mistake.
The OpenAPI editor has no Look, Layout or Draft with AI. Those belong to Mermaid and PlantUML diagrams. An API description is your team's own; the app draws what it says.
References to other files
A $ref to another part of the same description, such
as #/components/schemas/Pet, is followed. A schema
listed under components.schemas (in Swagger 2.0,
definitions) is shown by its name wherever it is
used, and has its own box.
A $ref to another file or a web address, such as
common.yaml#/Error, is never fetched.
The map and Details name it. Under the text, the editor says "Not
everything in this description is drawn" and what was left out,
and on the page, Details lists it under
Not shown. To show it, paste the whole description
as one file. Most API tools can export one, often called
"bundled".
Undo a mistake
- While you type, Ctrl+Z (Cmd+Z on a Mac) undoes your last change.
- Revert changes puts the text back the way it was when you opened the editor.
- Restore a previous version… lists up to five earlier versions of the description, each with its age. Choosing one loads it into the editor. The page does not change until you select Save.
- Cancel closes the editor without saving. On a diagram you have just inserted, it also removes the diagram.
For the whole page, use Confluence's Version history, under More actions (•••).