Vendor extensions

OpenAPI lets a spec carry its own facts in x-* fields, such as which plans can use an operation or whether it can’t be undone. Nimbus ignores them unless you list the ones you want. Listed fields are copied, unchanged, onto the pages that declare them, for your own components to show. Nimbus doesn’t render them itself.

api: [{
  collection: "api",
  spec: "./src/api/openapi.yaml",
  extensions: ["x-acme-plans", "x-acme-confirm", "x-acme-sensitive"],
}],

A version can set its own extensions, which replaces the entry’s list. Names must start with x-; x-nimbus-* is reserved. A listed name that no operation or field in a version declares logs one warning for that version.

Values appear on:

• operation pages, including webhooks, as page.extensions, from the operation object;
• every field, as field.extensions: parameters, request bodies, response fields, additional media types, and fields on schema pages. A parameter’s own value wins over its schema’s, and a property’s own value wins over the schema it references.

Tag pages, schema-page headers, response objects, the sidebar, Markdown versions and llms.txt don’t carry them. A field or operation with none of the listed names has no extensions.

The published spec keeps every x-* field, listed or not; set publishSpec: false to keep it unpublished.

Read them in your copies of the API components. In ApiBody.astro, which already imports Banner, add the two lines to the frontmatter and the markup where the notice should appear, such as below the page actions:

---
const extensions = page.kind === "operation" ? page.extensions : undefined;
const plans = extensions?.["x-acme-plans"];
---
{extensions?.["x-acme-confirm"] && (
  <Banner variant="caution" content="This action can't be undone." />
)}
{Array.isArray(plans) && <p>Available on {plans.join(", ")}.</p>}

In ApiFieldRow.astro, import Badge and add the badge beside the field’s other markers:

---
import { Badge } from "@/components/ui/badge";
---
{field.extensions?.["x-acme-sensitive"] === true && <Badge>Sensitive</Badge>}

Values are JSON. To type them, declare your extensions once, in a file of its own:

export {}; // makes this file a module, so the block below adds to Nimbus's types

declare module "@cloudflare/nimbus-docs/types" {
  interface ApiExtensions {
    "x-acme-plans": string[];
    "x-acme-confirm": boolean;
  }
}

page.extensions?.["x-acme-plans"] is then string[] | undefined; names you don’t declare stay JSON values.

Operation order

Section pages, the sidebar, the API home’s index and the Markdown versions list a section’s operations in the spec’s path order. x-nimbus-order on an operation moves it ahead: lower numbers come first, and operations without it follow in path order. A value that is not a number is ignored. Sections keep their order, and webhooks keep the spec’s. Set it in the spec, or in a step that prepares the spec before Nimbus reads it, for example from a CRUD rank so list, get, create, update and delete lead every section.

paths:
  /users:
    get:
      operationId: listUsers
      x-nimbus-order: 1
    post:
      operationId: createUser
      x-nimbus-order: 3
  /users/{id}:
    get:
      operationId: getUser
      x-nimbus-order: 2