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.

astro.config.tsts

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:

src/components/ui/api-layout/ApiBody.astroastro

---
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:

src/components/ui/api-field-row/ApiFieldRow.astroastro

---
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:

src/nimbus-api.d.tsts

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.