Add an OpenAPI reference

Nimbus currently supports OpenAPI 3.x. Nimbus turns a local OpenAPI document into a content collection that powers reference pages, navigation, alternate Markdown versions, search entries, llms.txt indexes, and stable links from prose documentation.

The OpenAPI document remains the source of truth. You do not create one MDX file per operation or schema.

To see a finished reference, open the weather demo: a Nimbus site with a 105-endpoint API in three versions, rendered on request on Cloudflare Workers.

Start a new site with it

The scaffolder can set the reference up for you: --api adds it beside the docs, at /api, and --template api makes it the whole site, at /. Pass your spec with --api ./openapi.yaml, or leave it out for a sample. See Scaffolder options.

npm create @cloudflare/nimbus-docs@latest -- my-docs --api ./openapi.yaml
npm create @cloudflare/nimbus-docs@latest -- my-docs --template api

Install with the recipe

Start with an OpenAPI 3.x document stored in your repository. If you have a Swagger 2.0 document, convert it first. src/api/openapi.yaml is the usual location, but Nimbus accepts any project-relative local path, a file in another git repository declared as a content source (spec: { source: "sdk", path: "openapi.json" }), or an inline document object. Remote specification URLs are not supported.

Run the API reference recipe from the project root inside your coding agent:

npx @cloudflare/nimbus-docs add api-reference

yarn nimbus-docs add api-reference

pnpm nimbus-docs add api-reference

bunx @cloudflare/nimbus-docs add api-reference

Inside a coding agent, Nimbus hands the recipe straight to it. From a regular shell or a script, add --print and pass the output to your agent. Without --print, a shell gets only instructions for piping it, on standard error, and no files change.

The recipe reviews its plan with you before changing files.

The recipe tells the agent to inspect your project, ask for the specification path and collection name, and then:

1. Installs the editable API layout and its parser dependencies.
2. Declares the specification in the Nimbus config in astro.config.ts.
3. Registers a loader-backed Astro content collection with one line.
4. Adds the HTML catch-all route. The starter’s shared Markdown route serves each page’s Markdown version.
5. Connects the collection to search, alternate Markdown versions, and llms.txt indexes.

Convert a Swagger 2.0 document

Nimbus reads OpenAPI 3.x only. A Swagger 2.0 document fails the build with Swagger 2.0 isn't supported. Convert it to OpenAPI 3.x first., followed by the document’s path.

Keep the Swagger document as your source, and generate a separate OpenAPI 3.x document from it with swagger2openapi:

npm i -D swagger2openapi@7.0.8

yarn add -D swagger2openapi@7.0.8

pnpm add -D swagger2openapi@7.0.8

bun add -d swagger2openapi@7.0.8

Run the conversion before Astro in your dev and build scripts, so the generated document always matches its source:

{
  "scripts": {
    "dev": "swagger2openapi src/api/swagger.yaml --yaml --outfile src/api/openapi.yaml && astro dev",
    "build": "swagger2openapi src/api/swagger.yaml --yaml --outfile src/api/openapi.yaml && astro build"
  }
}

Point the api entry’s spec at the generated document, ./src/api/openapi.yaml. The converter turns host, basePath, and schemes into servers, moves body and form parameters into request bodies, and converts security definitions. The development server watches the generated document, not the Swagger source, so restart dev after editing the source.

How the pieces fit

Why the specification is not in src/content

src/content/docs/ contains authored MDX entries. An OpenAPI document is an input to a loader: Nimbus projects it into many operation, tag, and webhook entries in the registered api collection, plus schema entries when schema pages are on.

Keeping the source under src/api/ makes that distinction visible. The path is only a convention; src/content/api/openapi.yaml also works if the configured spec points there.

Configuration generated by the recipe

The recipe declares the specification once, as an api entry in the Nimbus config:

import { defineConfig } from "astro/config";
import nimbus, {
  defineConfig as defineNimbusConfig,
} from "@cloudflare/nimbus-docs";

const nimbusConfig = defineNimbusConfig({
  site: "https://docs.example.com",
  title: "Acme Docs",
  api: [
    {
      collection: "api",
      spec: "./src/api/openapi.yaml",
    },
  ],
});

export default defineConfig({
  integrations: [nimbus(nimbusConfig)],
});

The reference is served where its route file is: src/pages/api/[...slug].astro serves api at /api, and src/pages/reference/api/[...slug].astro at /reference/api, with versions, openapi.json and the API catalog under it. See Collection URLs.

The recipe then registers a loader-backed collection under the same key, preserving existing collections and custom schema fields:

import { defineCollection } from "astro:content";
import {
  apiCollection,
  docsCollection,
  partialsCollection,
} from "@cloudflare/nimbus-docs/content";

export const collections = {
  docs: defineCollection(docsCollection()),
  partials: defineCollection(partialsCollection()),
  api: defineCollection(apiCollection()),
};

apiCollection() reads the api entry whose collection matches its key, so the specification is declared only once. The key tells Astro which loader turns that entry into content entries, and lets Nimbus find the collection during configuration and build validation.

To mount several specifications, add one api entry and one apiCollection() line for each. The build fails if a collection key has no api entry, or an api entry has no matching apiCollection() under its key. The error names both files. nimbus-docs check reports the same mismatches without a build.

In astro dev, editing a spec file re-indexes its pages. Editing the api entries restarts the dev server and re-indexes the reference, without a manual restart.

Verify the reference

Run a production build after adding or changing a specification:

pnpm build

Confirm that:

1. The build reports the number of indexed API pages.
2. The reference’s home and one operation page render: /api, or / in a site that is only the reference.
3. The same operation’s /index.md route returns Markdown.
4. The reference’s llms.txt lists its pages: /api/llms.txt, or /llms.txt at the root.
5. /nimbus-api/coordinates.json contains a known operation ID.
6. In a site with docs, a prose api.ref: link resolves to the expected route.

For request rendering, test the production Worker locally with Wrangler rather than relying only on Astro’s development server.

Next steps

• Routes and coordinates: choose the URLs your pages get.
• Cite API pages: link to operations from your guides.
• Code samples: control the samples on each operation.