redocusaurus

Redocusaurus is a Docusaurus preset that combines a content plugin and a theme to turn one or more OpenAPI/Swagger specs into fully themed API reference pages inside an existing Docusaurus site. Instead of standing up a separate Redoc deployment, teams add the preset to their docusaurus.config.js, point it at local spec files or remote URLs, and get versioned, searchable API docs that share the same navigation, header, footer, and dark-mode support as the rest of their documentation.

Under the hood it validates and bundles specs with Redocly’s openapi-core tooling, converts Swagger 2.0 specs to OpenAPI 3 automatically, and exposes swizzlable React components (Redoc, ApiDoc, ApiOperation, ApiSchema) so teams can customize rendering without forking the package. It ships fully typed, validates its own options with a Joi schema, and is maintained as part of a small monorepo alongside the underlying plugin and theme packages it wraps.

What You Get

• A Docusaurus preset bundling a content plugin and a Redoc-based theme in one package
• Automatic Swagger 2.0 to OpenAPI 3 conversion and spec bundling via Redocly’s openapi-core
• Dark mode support and Docusaurus-matched styling out of the box
• Swizzlable React components (Redoc, ApiDoc, ApiOperation, ApiSchema) for custom rendering
• Support for multiple specs, remote spec URLs, and per-spec routing

Common Use Cases

• Publishing REST API reference docs alongside product documentation on the same Docusaurus site
• Auto-generating versioned API docs pages from OpenAPI YAML/JSON files checked into a repo
• Embedding individual API operations or schemas inline in hand-written docs pages via ApiOperation/ApiSchema components
• Serving API reference for multiple services from one docs site, each with its own route and spec

Under The Hood

Architecture The monorepo splits into three packages that compose at runtime: packages/redocusaurus is a thin Docusaurus preset (src/index.ts) that globs an openapi/ folder (or a passed specs array) for *.openapi.{yaml,json} files, derives a route/id per spec, and wires up docusaurus-theme-redoc as the theme plus one docusaurus-plugin-redoc instance per spec. The plugin (packages/docusaurus-plugin-redoc/src/index.ts) implements Docusaurus’s plugin lifecycle directly — loadContent bundles and validates the spec via Redocly’s openapi-core, converts Swagger to OpenAPI 3 with Redoc’s loadAndBundleSpec, contentLoaded registers a route pointing at the ApiDoc theme component, and postBuild writes a static bundled-spec file for download. The theme package (packages/docusaurus-theme-redoc) supplies the swizzlable React components (Redoc, ApiDoc, ApiOperation, ApiSchema) and a configureWebpack hook that patches Node-only globals (tty, process.versions) so Redoc’s browser bundle works in Docusaurus’s webpack build. Changing the plugin’s route/content-loading contract would ripple into both the theme (which consumes SpecProps global data) and the preset (which assembles plugin instances), so the three packages are tightly coupled by design even though they publish independently.

Tech Stack TypeScript throughout (strict mode, ES2018 target, CommonJS output) on Node >=18, built with tsc and orchestrated via Yarn 4 workspaces (yarn workspaces foreach). Core dependencies are redoc (spec loading/conversion), @redocly/openapi-core (bundling, ref resolution, and lint-style problem reporting), and Docusaurus’s own @docusaurus/types/@docusaurus/utils/@docusaurus/utils-validation (Joi-based option schemas). The theme layer integrates directly with webpack via ProvidePlugin/NormalModuleReplacementPlugin/DefinePlugin to shim Node built-ins for the browser bundle. Releases are managed with Changesets, linting via ESLint (airbnb-typescript + Prettier) enforced through Husky/lint-staged pre-commit hooks, and CI runs a build workflow plus a Percy-based visual-regression workflow against a Vercel preview of the docs site.

Code Quality No unit or integration test files exist anywhere in the repository (packages/*/src and website/) — the only automated verification is the Percy visual-regression job that screenshots the deployed docs site, plus TypeScript’s own type checking (strict mode) and ESLint/Prettier enforced at commit time. Error handling is minimal but present: the plugin throws explicitly when a spec fails to parse, and bundling problems from @redocly/openapi-core are surfaced via console output during build rather than silently swallowed. Naming and file organization are consistent (one exported function per plugin/theme entry point, options/types split into dedicated files), and public option shapes are validated at runtime with Joi schemas in addition to compile-time types. Overall this reads as a small, typed, lint-enforced codebase that trades automated test coverage for strict typing and visual-regression checks on the rendered output.

API Design The public surface is deliberately small: consumers add one entry to a Docusaurus presets array and pass either an openapi.path folder to auto-discover specs or an explicit specs array, with sensible defaults (path: 'openapi', routeBasePath: '/api') so a minimal config needs almost no boilerplate. Advanced users can bypass the preset and use docusaurus-plugin-redoc/docusaurus-theme-redoc directly for multi-instance or custom setups, and the theme’s components are explicitly documented as swizzlable for deeper customization. Documentation is split between a concise root README, a dedicated Docusaurus-powered docs site with an Introduction/usage/examples section, and inline TSDoc comments on option types (e.g. PluginDirectUsageOptions), giving new users both a quick-start path and a deeper reference without needing to read source.