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>

---

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	npm i @rapidoc/hono	app.use(rapidoc({ specUrl: "/openapi.json" }))
Express	npm i @rapidoc/express	app.use(rapidoc({ specUrl: "/openapi.json" }))
Fastify	npm i @rapidoc/fastify	await fastify.register(rapidoc, { specUrl: "/openapi.json" })
FastAPI, Starlette	pip install rapidoc	setup_rapidoc(app)
ASP.NET Core	dotnet add package RapiDoc.AspNetCore	app.MapRapiDoc();
Go (net/http, chi, Gin, Echo, Fiber, Huma)	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	npm i @rapidoc/starlight
VitePress	npm i @rapidoc/vitepress
Docusaurus	npm i @rapidoc/docusaurus

React, Next.js, Vue, Nuxt, Angular and Svelte need no package: <rapi-doc> is a standard custom element. Setup for all of the above is in the framework integration guide.

Building one for another framework or language? Start from @rapidoc/embed and the integration guide: 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 <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.

This is the beginning of the README. Read the rest at the original. Read the full README ↗