The gentleman at REST

Spectacle generates beautiful static HTML documentation from OpenAPI / Swagger specifications.

The goal of Spectacle is to help you save time and look good by auto generating your API docs from your spec. The output is a clean three-column layout inspired by Stripe — a fixed sidebar, documentation on the left, and code examples on the right.

Supports OpenAPI 3.0, OpenAPI 3.1, and Swagger 2.0 (auto-converted).

• OpenAPI 3.x + Swagger 2.0 — full support, with automatic Swagger-to-OpenAPI conversion
• Beautiful three-column layout — sidebar navigation, docs, and dark code panel
• Dark mode — toggle with a button, respects system preference, persists with localStorage
• Client-side search — / or Ctrl+K to search endpoints and models instantly
• Auto-generated code samples — cURL, JavaScript (fetch), and Python (requests) for every operation
• Synced language tabs — switch language in one example, all others follow
• Shiki syntax highlighting — VS Code-quality highlighting at build time
• Markdown descriptions — full markdown rendering in all description fields
• Dev server with live reload — spectacle dev watches your spec and reloads the browser
• Theming — override any CSS variable via spectacle.json — colors, fonts, spacing
• Custom branding — logo and favicon via config
• Embeddable output — generate partial HTML for embedding into your own site
• Zero client-side dependencies — no frameworks shipped to the browser

Install Spectacle:

npm install -g spectacle-docs

Generate docs from your spec:

spectacle build your_api.yaml -o docs/

That's it. Open docs/index.html in your browser.

spectacle build <spec> [options]    Build static documentation
spectacle dev <spec> [options]      Start dev server with live reload
spectacle validate <spec>           Validate a spec file
spectacle <spec>                    Shorthand for 'spectacle build'

# Build docs to a custom directory
spectacle build api.yaml -o public/docs

# Start dev server with live reload
spectacle dev api.yaml

# Validate a spec without building
spectacle validate api.yaml

# Build with a custom logo
spectacle build api.yaml --logo ./logo.png -o docs/

Create a spectacle.json in your project root to configure branding and theming. CLI flags take precedence over config values.

{
  "logo": "./logo.png",
  "favicon": "./favicon.ico",
  "theme": {
    "--color-accent": "#e11d48",
    "--font-sans": "'IBM Plex Sans', sans-serif",
    "--sidebar-width": "280px"
  }
}

The theme object accepts any CSS custom property. Here are the available variables:

import { buildDocs } from 'spectacle-docs';

const result = await buildDocs({
  specSource: './api.yaml',
  outputDir: './docs',
  logo: './logo.png',
  favicon: './favicon.ico',
  themeOverrides: {
    '--color-accent': '#e11d48',
  },
});

console.log(result.spec.info.title);      // "My API"
console.log(result.spec.operations.length); // 42

git clone https://github.com/sourcey/spectacle.git
cd spectacle
npm install
npm run build
npm test

src/
  cli.ts              CLI entry point (citty)
  index.ts            Programmatic API
  config.ts           spectacle.json loader
  dev-server.ts       Dev server with live reload
  core/               Spec processing pipeline
    loader.ts         Load from file/URL
    parser.ts         Validate and dereference $refs
    converter.ts      Swagger 2.0 → OpenAPI 3.x
    normalizer.ts     OpenAPI → internal model
    types.ts          Internal types
  components/         Preact components (SSG)
    layout/           Page, Sidebar, Head
    openapi/          Operation, Parameters, Responses, etc.
    schema/           SchemaView, ExampleView
    ui/               Badge, CodeBlock, Markdown, SectionLabel
  renderer/           HTML generation
    static-renderer.ts  Preact → HTML string
    html-builder.ts     Assemble HTML + CSS + JS
    context.ts          Render context
  client/             Browser JavaScript (vanilla JS)
    sidebar.js        Drawer toggle, close on outside click/Escape
    scroll-tracker.js IntersectionObserver nav highlighting
    tabs.js           Synced language tab switching
    copy.js           Clipboard copy with feedback
    theme-toggle.js   Dark/light mode toggle
    search.js         Client-side search dialog
  themes/
    default/          Default theme CSS

npm test           # Run all tests
npm run test:watch # Watch mode
npm run typecheck  # TypeScript type checking
npm run lint       # ESLint

Please use the GitHub issue tracker if you have any ideas or bugs to report.

All contributions are welcome.

Good luck and enjoy Spectacle!

MIT