Editing that knows which OpenAPI version you are on
The editor now shows the OpenAPI version your document declares and creates new nodes using the constructs that version allows — a nullable field comes out as `nullable: true` on 3.0 and as a null type union on 3.1. Webhooks, 3.1's other root section, are visible and editable for the first time.
In this release
- New
The declared version, always in view
A badge beside the document title says which OpenAPI version you are editing against, and warns when the document declares none.
- New
Nullable fields, spelled the right way
Schemas and parameters have a nullable toggle that writes what your version understands, and shows you the keyword before you commit to it.
- Fixed
Nullable 3.0 fields show up as nullable
A field marked `nullable: true` now reads as `string | null` in the generated TypeScript and the Docs tab, the same as the 3.1 spelling always did.
- New
Webhooks are part of your API
A 3.1 document's webhooks get their own explorer section, and turn up in search, docs, diffs and linting exactly as endpoints do. You can create, rename and delete them.
- Improved
Constructs your version lacks are explained, not hidden
Mutual TLS security schemes stay visible on a 3.0 document, disabled with the version that would give them to you.
OpenAPI 3.0, 3.1 and 3.2 are not one format. They disagree about how you say a value may be null, which security schemes exist, and how a streaming response describes its payload. The editor read the openapi version to pick a validator and otherwise ignored it — so it would happily write a construct your document's own tooling rejects, and you found out from a lint error afterwards.
Authoring is now version-aware.
The version, where you can see it
The document header carries the version the document declares. If it declares none, the badge says so, and new nodes are created as 3.1 until you set one.
Nullability, the way your version spells it
Schemas and parameters gained a Nullable toggle. On a 3.0 document it writes nullable: true; on 3.1 and later it writes a ["string", "null"] type union. The keyword you will get is printed next to the toggle, so the difference is visible before you create anything. Empty required lists — legal in 3.1, rejected by 3.0 — are left out of 3.0 documents.
Missing constructs say why
A construct your version does not have stays on screen, disabled, with the release that introduced it. Mutual TLS security schemes on a 3.0 document read "Mutual TLS security schemes arrived in OpenAPI 3.1" rather than quietly not being there.
Webhooks, at last
A webhook is a call your API makes: an event it sends to a URL its consumer owns. OpenAPI 3.1 added webhooks as a root section for describing them, beside paths — and the editor did not model it at all. A document with webhooks loaded without complaint and every one of them was invisible: not in the explorer, not in search, not in the docs, not in a diff. You could open such a spec, change something else, publish, and never learn that a whole part of your API had gone unseen.
They now get a section of their own in the explorer — beside Endpoints rather than buried in it, because a webhook is not a route anyone calls — and are read everywhere an endpoint is. Creating one asks for the event name that identifies it, newPet or order.created, rather than a URL: the one thing a webhook does not have is a path, so there is no leading slash and no path templating. On a 3.0 document the option is there and disabled, saying which release would give it to you.
Nullable fields you could not see
A 3.0 document marks a field nullable with nullable: true. The generated TypeScript and the Docs tab only understood the 3.1 spelling, so those fields read as though they could never be null — precisely the thing a caller needs the type to warn them about. Both now agree: string | null, whichever way the document says it.
Nothing here blocks editing an existing document: only what the editor creates follows the declared version, so a document mid-migration stays editable.