RapiDoc

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.

---

Features

• 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.

---

Quick Usage

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>

---

Generating a Developer Portal with RapiDoc Portal

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).

1. Create a portal project

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

2. Describe your portal

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.

3. Preview locally

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

4. Build and host

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.

What happens during a build

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 holds the example portals used to dog-food these packages.

---

Repository Architecture

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/                       # See tests/README.md
│
├── package.json                 # Monorepo root configuration (workspaces)
└── README.md

---

Development & Build Instructions

Prerequisites

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

1. Installation

Clone the repository and install dependencies across all workspaces:

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

2. Development Server & Live Debugging

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.

---

3. Build Process & Workspace Integration

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:

Core Library Production Build (npm run build:rapidoc)

• 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.

Core Library Development Build (npm run build:rapidoc:dev)

• 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.

Full Monorepo Build (npm run build)

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

---

4. How Astro Docs Consumes RapiDoc (rapidoc-min.js)

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.

---

5. NPM Command Reference

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

Development & Live Preview

Command	Workspace	Description
npm run dev	docs	Launches Astro documentation & showcase dev server (http://localhost:4321) with live unminified RapiDoc ESM directly from source.
npm run stop	docs	Terminates background Astro dev server processes.
npm run preview	docs	Previews the production build of the documentation site (docs/dist) locally.

Building

Command	Workspace	Description
npm run build	Monorepo	Sequentially builds production RapiDoc library bundle and the Astro documentation site.
npm run build:rapidoc	rapidoc	Compiles production, minified Web Component bundle to packages/rapidoc/dist/rapidoc-min.js.
npm run build:rapidoc:dev	rapidoc	Compiles unminified Web Component bundle with source maps & console logs to packages/rapidoc/dist/.
npm run build:docs	docs	Builds the production Astro documentation site into docs/dist/ (and syncs bundle to generated-docs/).
npm run build:size	rapidoc	Builds RapiDoc with ANALYZE=true and opens an interactive bundle visualizer (dist/stats.html).

Testing & Benchmarks

Command	Workspace	Description
npm run test:unit	Monorepo	Runs Node.js native unit tests (tests/unit/*.test.js) for schema parsers and AST converters.
npm run test:perf	Monorepo	Runs spec parsing, circular ref, and dereferencing benchmarks (tests/perf/benchmark.js).
npm run test:render	Monorepo	Measures headless browser rendering performance across render styles using Puppeteer (tests/perf/render-benchmark.js).

Code Quality & Formatting

Command	Workspace	Description
npm run lint	Monorepo	Runs oxlint (default rules, no config) across packages, docs, tests and scripts.
npm run format	Monorepo	Checks formatting with oxfmt (default style, no config) across packages, docs, tests and scripts.
npm run format-fix	Monorepo	Formats the same files with oxfmt.

Publishing

Command	Workspace	Description
npm run publish:rapidoc	rapidoc	Publishes the rapidoc package to the npm registry.

---

Documentation Site & GitHub Pages Deployment

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

Deployment via GitHub Actions

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.

---

Specs Organization

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 rapidocui.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).

---

Roadmap

• 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

---

License

MIT © Mrinmoy Majumdar