OpenAPI / AsyncAPI

Drop in an OpenAPI spec and get a native API reference — one real page per operation, in your sidebar and search.

Point Blume at an OpenAPI spec and it generates a native API reference: one real page per operation, grouped by tag in a tab-scoped sidebar, with schema tables, request/response examples, and generated code samples. Because each operation is a genuine Blume page, it gets its own URL, shows up in site search and llms.txt, and gets an Open Graph image — the same as any hand-written doc.

openapi: {
  enabled: true,
  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
}

That mounts the reference at /reference (an overview page) with each operation at /reference/<tag>/<operation>, and adds a header tab. The spec is either an http(s) URL or a path to a local file in your project. Blume parses it with Scalar’s OpenAPI parser — Swagger 2.0 and OpenAPI 3.0 specs are upgraded to 3.1 automatically.

A local spec

A relative path is resolved from your project root and read at build time. Both JSON and YAML work:

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
}

Route

route controls where the reference mounts — the overview page and the prefix for every operation route (and the header tab’s target):

openapi: {
  enabled: true,
  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
  spec: "./openapi.yaml",
}

Code samples and schemas

codeSamples picks which languages render per operation (built in: curl, js, python); expandSchemas starts nested schema rows expanded rather than collapsed:

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  codeSamples: ["curl", "js"],
  expandSchemas: true,
}

Multiple specs

Use sources to publish more than one spec. Each source gets its own overview route, operation pages, and header tab. Give each a label (used for the tab and to derive its route), or set an explicit route:

openapi: {
  enabled: true,
  sources: [
    { label: "Public API", spec: "./public.json" },   // → /reference/public-api
    { label: "Admin API", route: "/admin", spec: "./admin.json" },
  ],
}

spec is shorthand for a single-entry sources, so you only reach for sources when you have more than one.

The Scalar renderer

The native renderer is the default. If you’d rather embed Scalar’s self-contained API reference — its own sidebar, search, theme, and “Try it” playground on a single route — set renderer: "scalar":

openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  theme: "purple",   // a Scalar theme name (Scalar renderer only)
}

A Scalar-rendered reference is a self-contained embed on its own route — it doesn’t weave into Blume’s sidebar, search, or llms.txt. Its “Try it” playground calls your target API directly from the browser (Blume doesn’t proxy), so the API must allow cross-origin requests from the docs site (Access-Control-Allow-Origin). theme and the playground apply to the Scalar renderer only.

AsyncAPI

Event-driven APIs use a sibling asyncapi block with the same shape. AsyncAPI is rendered by Scalar (the native renderer is OpenAPI-only for now); only the default route differs (/events):

asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
}