OpenAPI versions

api.openapi({ version }) renders one OpenAPI version from the model defineApi builds. The versions describe the same operations, schemas and errors; they differ only where an older version has no field for something.

const legacy = api.openapi({ version: "3.0" }).document;
const current = api.openapi().document; // 3.1
const latest = api.openapi({ version: "3.2" }).document;

The pinned spec versions and the conformance tests are on the OpenAPI standards page.

Every versionCopy Anchor Link

• Path parameters that every operation on a path shares move to the Path Item, so they are declared once.
• Webhooks from the webhooks option become the root webhooks section (3.1 and later). Each one is a post with the operation id on<Event>, a JSON request body, and a 2XX response. With standardWebhooks: true it also lists the webhook-id, webhook-timestamp and webhook-signature headers.
• Fragments are merged after the document is rendered, then each operation's extend (see customize the model).
• The finished document is checked: duplicate operation ids, security requirements that name no scheme, path parameters without a declaration and the reverse, and local $refs that point nowhere. See diagnostics.

3.1Copy Anchor Link

3.1 is the default and what createOpenApi renders without a version. It sets jsonSchemaDialect to JSON Schema 2020-12, which is the dialect of every generated schema.

The fields that only 3.2 defines are kept as extensions, so tools that know them can still read them:

The x-better-supabase- fields follow extensionPrefix.

3.2Copy Anchor Link

3.2 renders those fields natively:

• $self on the document and name on each server.
• Nested tags: parent, kind and summary on each tag.
• itemSchema for a route with stream, so each event of a text/event-stream response has a schema.
• oauth2MetadataUrl on the oauth2 preset, pointing at the Supabase Auth server metadata.
• The query method. A route with method: "query" is a query operation in 3.2 and later, and is left out of 3.0 and 3.1 with a method-unsupported warning.

3.0Copy Anchor Link

3.0 is for tools that don't read 3.1 yet. The document has no jsonSchemaDialect and no webhooks (a model with webhooks gets a webhooks-unsupported warning), and info.summary and license.identifier are left out. Every schema is rewritten into the OpenAPI 3.0 schema object, after the fragments are merged:

toOpenApi30Schema(schema) from better-supabase/openapi is that rewrite, for schemas you serve yourself.

3.3 previewCopy Anchor Link

"3.3-preview" follows the OpenAPI v3.3-dev branch and the Security Profiles proposal at the commits pinned in SPEC_PINS. It is never the default: every render adds a preview-version warning, and the document carries x-better-supabase-preview with the pinned commit. Fields can change before 3.3 is released, so use it to try the proposal, not to publish.

Besides everything 3.2 renders, the preview:

• moves a security that every operation on a path shares to the Path Item;
• renders security schemes of the Security Profiles type (type: "profile") and the securityProfileRequirements option as components.securityProfileRequirements.

const preview = api.openapi({ version: "3.3-preview" });
// preview.diagnostics has { code: "preview-version", severity: "warning" }

Other versions leave profile schemes out, with every requirement that names one, and report preview-only (severity info).

TypesCopy Anchor Link

OpenApi30Document, OpenApi31Document, OpenApi32Document and OpenApi33PreviewDocument from better-supabase/openapi type each version, and OpenApiDocument<V> picks one by version. transform and the result of api.openapi({ version }) use them, so a field another version doesn't have is a type error.