---
title: "Vendor extensions"
description: "Show your spec's own x-* fields on API pages, typed, in your copies of the API components."
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```ts title="astro.config.ts"
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](/api-reference/openapi/options#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:

```astro title="src/components/ui/api-layout/ApiBody.astro"
---
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:

```astro title="src/components/ui/api-field-row/ApiFieldRow.astro"
---
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:

```ts title="src/nimbus-api.d.ts"
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.

Source: https://nimbus-docs.com/api-reference/openapi/extensions/index.mdx