Docs Viewer

Reusable OpenAPI and AsyncAPI docs helpers for Bun projects.

What it does

• builds OpenAPI HTML with Redocly
• builds AsyncAPI HTML from a shared template
• serves generated docs from a Bun static server

Exports

• buildDocs(specs, options)
• serveDocs(options)

CLI

bunx docs-viewer docs/openapi docs/asyncapi --watch

Options:

• --openapi <selector>
• --asyncapi <selector>
• --output-dir <dir>
• --port <port>
• --watch
• --build-only

Usage

import { buildDocs, serveDocs } from "@joadr/docs-viewer";

await buildDocs(
  [
    {
      kind: "openapi",
      source: "docs/openapi/accounts.yaml",
      output: "docs/openapi/accounts.html",
      title: "Ledger Accounts API",
    },
    {
      kind: "asyncapi",
      source: "docs/asyncapi/accounts.yaml",
      output: "docs/asyncapi/accounts.html",
      title: "Ledger Accounts Events",
    },
  ],
  { cwd: process.cwd() },
);

serveDocs({ rootDir: "docs", port: 4173 });

Notes

• buildDocs writes HTML to the paths you pass in.
• serveDocs serves an existing docs directory.
• the package is designed to be wrapped by a small CLI or script in each repo.
• bun run build emits dist/ so the published package works with both bunx and npx.
• if you omit --output-dir, docs are written to /tmp/docs-viewer/<repo-name>.
• if you omit --port, the server uses 4173.
• --build-only generates docs without starting the server.

Release

Manual releases use the GitHub Actions Release workflow with a version input. The workflow publishes to npm, publishes to GitHub Packages, and creates a GitHub Release with notes generated from commit history.