RapiDoc

Custom Element for OpenAPI / Swagger Spec Viewing

RapiDoc is a fast, responsive, and customizable Web Component that renders beautiful, interactive API documentation from OpenAPI (Swagger) specifications.

• OpenAPI Support: Full support for OpenAPI 3.0.x, 3.1.x, and Swagger 2.0.
• Framework Agnostic: Works with plain HTML, React, Vue, Angular, Svelte, or Lit.
• Built-in API Console: Call and test APIs directly from the documentation.
• Usability First:
  • Models and examples expanded by default — no endless clicking to reveal schemas.
  • Pre-populated sample data in request fields.
  • Side-by-side request and response view for quick comparison.
• Branding & Theming:
  • Dark and Light themes out of the box.
  • Easily customizable brand colors, typography, logos, and header styling.
• Customizable Layouts:
  • Three distinct rendering styles: read, view, and focused.
  • Inject custom content using web component slots (fixed-header, overview, servers, auth).
• Fast & Lightweight: Built using Lit with zero unnecessary overhead.

Include the script in your HTML page and use the <rapi-doc> custom element:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
</head>
<body>
  <rapi-doc
    spec-url="https://petstore.swagger.io/v2/swagger.json"
    theme="dark"
    render-style="read"
  ></rapi-doc>
</body>
</html>

Beyond embedding <rapi-doc> in a page, this repository ships RapiDoc Portal: a docs-as-code engine that turns a folder of OpenAPI specs and guides into a complete static developer portal (home page, API catalog, interactive API references, guides and full-text search).

npm create rapidoc@latest my-portal
cd my-portal && npm install

Already using the CLI, or adding a portal to a repo that has OpenAPI files? npx rapidoc init [dir] scaffolds the same project and builds apis: from the specs it finds there. The project depends on @rapidoc/cli (the rapidoc command) and @rapidoc/portal (the engine it runs for dev and build).

This scaffolds:

my-portal/
├── rapidoc.config.yaml     # Site, header, navigation tabs, theme, APIs
├── specs/api.yaml          # Your OpenAPI 3.x / Swagger 2.0 specs
└── docs/                   # Guides in Markdown (.md), MDX (.mdx) or Markdoc (.markdoc); docs/index.* is the home page

Add specs to specs/ and guides to docs/, then wire them up in rapidoc.config.yaml:

site:
  title: Acme Developer Portal
navigation:                     # the header tabs; a documentation tab has its own sidebar
  - label: Guides
    items:
      - getting-started         # docs/getting-started.md
  - label: Orders API
    api: orders
  - label: API Catalog
    catalog: true
apis:
  - id: orders
    spec: ./specs/orders.yaml   # reference page at /apis/orders
    category: Commerce          # groups APIs on the /catalog page

Every key is checked: a typo fails the build with its location. Coming from Redocly or Zudoku? npx rapidoc migrate --from redocly|zudoku converts its config. The full reference is in packages/rapidoc-portal/README.md.

npx rapidoc dev        # http://localhost:4321, reloads as you edit docs, specs or config

npx rapidoc build      # static site in ./dist

Upload dist/ to any static host (GitHub Pages, Netlify, S3, Nginx). Check specs before publishing with npx rapidoc validate ./specs/orders.yaml.

1. rapidoc.config.yaml is loaded and validated.
2. A temporary Astro project is created in my-portal/.rapidoc-temp/ (one folder per run) with normalized copies of your guides, your specs, the rapidoc-min.js bundle and a search index.
3. Astro + Starlight render the guides and the home page; the portal's own pages render the API catalog and one RapiDoc reference page per API.
4. The static site is written to dist/.
5. The temporary project is deleted, so your project is left exactly as it was apart from dist/.

See packages/rapidoc-portal/README.md for the full configuration reference, the guide syntax (Markdoc tags, MDX components) and the programmatic API. The rapi-portal-demo repository is the reference portal used to dog-food these packages.

This repository is structured as a Monorepo using workspaces, compatible with Node/npm, pnpm, and Bun:

rapidoc/
├── packages/
│   ├── rapidoc/                 # Core Web Component library (published as "rapidoc")
│   │   ├── src/                 # Web component source code (Lit + modern ESM)
│   │   ├── dist/                # Production bundle (rapidoc-min.js)
│   │   ├── package.json         # Library package config
│   │   └── vite.config.mjs      # Dedicated library build config
│   │
│   ├── rapidoc-cli/             # The `rapidoc` command (@rapidoc/cli): init, dev, build, validate, migrate
│   │   ├── src/                 # CLI source code
│   │   └── package.json
│   │
│   ├── rapidoc-portal/          # Docs-as-code developer portal engine (@rapidoc/portal)
│   │   ├── src/engine/          # Build & dev pipeline (temp workspace, Astro + Starlight)
│   │   ├── src/pages/           # Portal pages: home, catalog, API reference
│   │   └── package.json
│   │
│   └── create-rapidoc/          # Project scaffolder (npm create rapidoc)
│       └── package.json
│
├── docs/                        # Astro documentation & showcase site (GitHub Pages)
│   ├── src/                     # Astro pages, components, and layouts
│   │   ├── pages/examples/      # Public showcase pages (code-highlight, petstore, etc.)
│   │   └── pages/tests/         # Internal test & edge-case pages
│   ├── public/
│   │   ├── specs/               # PUBLIC showcase specs (used by /examples)
│   │   └── specs-test/          # INTERNAL test specs (edge cases & parser fixtures)
│   │       └── parser/          # Malformed & validation test specs
│   ├── astro.config.mjs         # Astro site configuration
│   └── package.json             # Workspace package "docs"
│
├── tests/
│   └── visual/                  # Automated visual regression test suite (Playwright)
│
├── package.json                 # Monorepo root configuration (workspaces)
└── README.md

• Node.js: >= 22.12.0 (or Bun)
• npm (or bun)

Clone the repository and install dependencies across all workspaces:

git clone https://github.com/rapi-doc/RapiDoc.git
cd RapiDoc
npm install

Start the local documentation and interactive examples showcase:

# Start dev server (http://localhost:4321)
npm run dev

# Stop background dev server
npm run stop

• Open http://localhost:4321 in your browser.
• Live Unminified ES Modules: In development mode (npm run dev), the Astro dev server bypasses pre-compiled production bundles and serves live ES modules directly from packages/rapidoc/src/index.js.
• Full DevTools & Console Visibility: All console.log, console.warn, console.error, and debugger breakpoints remain completely intact with original file names and exact line numbers (e.g., rapidoc.js:516).
• Instant Browser Reloading: Component changes in packages/rapidoc/src/ trigger immediate hot reloads without waiting for a full Rollup/Vite compilation cycle.

This monorepo contains multiple packages: the core Web Component library (packages/rapidoc) and the documentation showcase site (docs). The build system coordinates them as follows:

• Workspace: packages/rapidoc
• Output: packages/rapidoc/dist/rapidoc-min.js
• Compiles the RapiDoc custom element in library mode using Vite 6.
• Inlines and bundles runtime dependencies (lit, @scalar/openapi-parser, marked, microlighter, github-slugger) into a standalone bundle with zero runtime external dependencies.
• Minifies Lit templates using @lit-labs/rollup-plugin-minify-html-literals.
• Strips console.* and debugger calls via a custom esbuild transform for optimal performance and clean production distribution.
• Injects the license and version header banner.

• Workspace: packages/rapidoc
• Output: packages/rapidoc/dist/rapidoc-min.js + packages/rapidoc/dist/rapidoc-min.js.map
• Compiles the standalone library bundle with mode: 'development'.
• Disables template and esbuild minification, preserves all console and debugger statements, and emits full external source maps.
• Useful when you need to test the bundled <rapi-doc> script tag artifact in external standalone HTML pages or apps with full DevTools logging.

• Scope: Root monorepo
• Sequentially executes npm run build:rapidoc followed by npm run build:docs.

Astro documentation and example pages include the component via <script type="module" src="/rapidoc/rapidoc-min.js"></script>. How this URL is resolved depends on whether you are developing locally or generating a production build:

1. During Local Development (npm run dev):

   • The Astro dev server middleware (in docs/astro.config.mjs) intercepts all requests for /rapidoc/rapidoc-min.js (and /rapidoc/rapidoc.js).
   • Instead of reading any pre-built static file, it directly imports and serves packages/rapidoc/src/index.js live through Vite's module pipeline.
   • You get instant HMR, unminified source code, active console.* logging, and sourcemaps with exact line numbers in browser DevTools. Neither dist/ nor generated-docs/ is served during development.

2. During Production Site Build (npm run build:docs / npm run build):

   • The custom build-rapidoc Vite plugin in docs/astro.config.mjs runs during build initialization:
     1. It verifies that packages/rapidoc/dist/rapidoc-min.js is compiled (triggering a Vite library build if missing).
     2. It copies packages/rapidoc/dist/rapidoc-min.js into docs/dist/rapidoc/rapidoc-min.js, so that the static site deployed to GitHub Pages serves the production bundle.
     3. If the local docs/generated-docs/ directory exists, it also synchronizes rapidoc-min.js into docs/generated-docs/rapidoc/rapidoc-min.js to keep the static snapshot folder up to date with the newly built component.

All primary commands can be run from the root of the repository:

The documentation site is built with modern Astro using clean, extensionless URLs (/api, /examples, /list, /quickstart).

When code is pushed to master or main, the deploy-docs.yml GitHub Action automatically:

1. Compiles the rapidoc library bundle (packages/rapidoc/dist/rapidoc-min.js).
2. Builds the Astro documentation site into docs/dist/ (npm run build).
3. Deploys the static output directory (docs/dist/) directly to GitHub Pages using @actions/deploy-pages.

Note on GitHub Pages Configuration: In repository settings under Settings → Pages, set Source to GitHub Actions. This keeps the repository clean by eliminating the need to commit compiled static HTML files into git branches.

OpenAPI specs are organized inside docs/public/ based on their visibility and purpose:

• docs/public/specs/: Public showcase specs referenced in example-list.yaml and displayed on rapidocweb.com (e.g., petstore.yaml, code-highlight.yaml, auth.yaml).
• docs/public/specs-test/: Internal edge-case and boundary specs used for UI verification and regression tests (e.g., circular-refs.yaml, xxx-of-combinations.yaml).
• docs/public/specs-test/parser/: Malformed or invalid specs used to test CLI validation and error reporting (e.g., invalid-syntax.yaml, missing-info.yaml, broken-ref.yaml).

• Modernize project dependencies (Vite + Astro + Node 22+)
• Restructure as a multi-package Monorepo
• Build rapidoc-cli for OpenAPI linting and local zero-config previews
• Build rapidoc-portal, a docs-as-code developer portal engine (Astro + Starlight)
• Automated visual regression testing suite with Playwright
• Web Content Accessibility Guidelines (WCAG 2.1) compliance enhancements

MIT © Mrinmoy Majumdar