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>

---

Repository Architecture

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

astro-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/             # Command-line utility (lint, preview, bundle)
│   │   ├── src/                 # CLI source code
│   │   └── package.json
│   │
│   └── rapidoc-portal/          # PocketBase developer portal to host & secure specs
│       └── 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

---

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

Building

Testing & Benchmarks

Code Quality & Formatting

Publishing

---

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

---

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 with PocketBase for developer API portals
• Automated visual regression testing suite with Playwright
• Web Content Accessibility Guidelines (WCAG 2.1) compliance enhancements

---

License

MIT © Mrinmoy Majumdar