# 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](https://lit.dev/) with zero unnecessary overhead.
---
## Quick Usage
Include the script in your HTML page and use the `` custom element:
```html
```
---
## Integrations
Official packages that add a RapiDoc reference to your app or docs site. Each one ships a pinned RapiDoc bundle (nothing is loaded from another site unless you ask for a CDN), takes the same options, and serves the OAuth sign-in return page for you.
**Server frameworks**: the reference at `/docs`, reading your app's OpenAPI document.
| Framework | Install | Use |
| :--- | :--- | :--- |
| [Hono](packages/rapidoc-hono) | `npm i @rapidoc/hono` | `app.use(rapidoc({ specUrl: "/openapi.json" }))` |
| [Express](packages/rapidoc-express) | `npm i @rapidoc/express` | `app.use(rapidoc({ specUrl: "/openapi.json" }))` |
| [Fastify](packages/rapidoc-fastify) | `npm i @rapidoc/fastify` | `await fastify.register(rapidoc, { specUrl: "/openapi.json" })` |
| [FastAPI, Starlette](integrations/rapidoc-python) | `pip install rapidoc` | `setup_rapidoc(app)` |
| [ASP.NET Core](integrations/rapidoc-dotnet) | `dotnet add package RapiDoc.AspNetCore` | `app.MapRapiDoc();` |
| [Go (`net/http`, chi, Gin, Echo, Fiber, Huma)](https://github.com/rapi-doc/rapidoc-go) | `go get github.com/rapi-doc/rapidoc-go` | `rapidoc.Handler(rapidoc.Options{SpecURL: "/openapi.json"})` |
**Documentation sites**: API reference pages in your site's own layout, with the operations in its sidebar.
| Site generator | Install |
| :--- | :--- |
| [Starlight](packages/rapidoc-starlight) | `npm i @rapidoc/starlight` |
| [VitePress](packages/rapidoc-vitepress) | `npm i @rapidoc/vitepress` |
| [Docusaurus](packages/rapidoc-docusaurus) | `npm i @rapidoc/docusaurus` |
React, Next.js, Vue, Nuxt, Angular and Svelte need no package: `` is a standard custom element. Setup for all of the above is in the [framework integration guide](https://rapidocui.com/docs/integrations/front-end/).
Building one for another framework or language? Start from [`@rapidoc/embed`](packages/rapidoc-embed) and the [integration guide](https://rapidocui.com/docs/integrations/build-your-own/): it defines the options, routes and HTML every integration shares, with fixtures to test a port against.
---
## Generating a Developer Portal with RapiDoc Portal
Beyond embedding `` 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
```bash
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:
```text
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`:
```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`](packages/rapidoc-portal/README.md#configuration-rapidocconfigyaml).
### 3. Preview locally
```bash
npx rapidoc dev # http://localhost:4321, reloads as you edit docs, specs or config
```
### 4. Build and host
```bash
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`](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**:
```text
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](https://bun.sh/))
- **npm** (or `bun`)
### 1. Installation
Clone the repository and install dependencies across all workspaces:
```bash
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:
```bash
# 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](https://vitejs.dev/).
- 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 `` 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 ``. 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/workflows/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](docs/src/data/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
- [x] Modernize project dependencies (Vite + Astro + Node 22+)
- [x] 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
---
## Sponsors
- Hosting sponsored by [Simafri](https://www.simafri.com/en/managed-vps/) (managed VPS)
- AI coding tools sponsored by [Anthropic](https://www.anthropic.com) (Claude)
---
## License
MIT © [Mrinmoy Majumdar](https://github.com/mrin9)