OpenAPI: fix a problem
What each message in the OpenAPI editor means and what to do about it, and what the OpenAPI diagram does not do.
On this page
When it does not draw
The line under the text says what is wrong, in the words below. The editor will not save a description that does not draw.
- "The YAML could not be read" or "The JSON could not be read"
- The text has a mistake on or near the line it names: often an indent that does not line up, or a tab. YAML allows only spaces for indenting.
- "This is not an OpenAPI description"
-
The description needs an
openapi: 3.0.3(or another 3.x version) orswagger: "2.0"line at its top level, not indented. - "This version is not supported"
-
The text says a version the app cannot show, such as
openapi: 4.0orswagger: "1.2". The message names the version it found. Convert a Swagger 1.x description to 2.0 or OpenAPI 3 in your API tool first. - "This description is nested too deeply"
- It has more levels inside each other than can be read, usually from a mistake in brackets or indenting.
- "This description could not be read"
- Something in it is not in the shape OpenAPI describes. Check it in an OpenAPI editor or validator, and paste it again.
- "This description is too large"
- It is over 1,000,000 characters. Paste a part of it, such as one tag.
- Some endpoints or schemas are missing
- Open Details: Not shown, at its top, says what was left out and why. A reference to another file, or a description over the limits below, are the usual reasons.
The app reads up to 500 endpoints and 300 schemas, and stops earlier on a very large or very repetitive description, with the note "The description is too large to show in full; the rest is left out." Whatever is over a limit is left out rather than slowing the page down.
What it does not do
- No "Try it out". The app declares no connection to anywhere outside Atlassian, so it cannot call your API. You can check this on the app's Marketplace listing and in Data and security.
- Descriptions are plain text. Markdown in a description is shown as written, not formatted, and links in it are not made clickable.
- Not listed yet: webhooks, callbacks and security schemes. The editor says when a description has webhooks.
- No editing of the API. The description is the source; to change the map, change the text.