Docusaurus OpenAPI Docs Administrator & Developer Guide

1. Architecture Overview

Docusaurus OpenAPI Docs is a monorepo containing three npm packages that extend Docusaurus with OpenAPI documentation capabilities. The plugin reads OpenAPI spec files (2.0/3.0/3.1), resolves $ref pointers and circular references, converts the specification into MDX pages with compressed API metadata, and generates sidebar navigation. The theme renders those pages with an interactive API explorer powered by Redux state management, Postman code generators, and React form components.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                        docusaurus.config.ts                         │
│  plugins: [docusaurus-plugin-openapi-docs]                          │
│  themes:  [docusaurus-theme-openapi-docs]                           │
└──────────┬──────────────────────────────────┬───────────────────────┘
           │                                  │
           ▼                                  ▼
┌─────────────────────────┐     ┌──────────────────────────────────┐
│  Plugin (Build-time)     │     │  Theme (Runtime / Client-side)    │
│                          │     │                                    │
│  OpenAPI Spec ──►        │     │  ApiItem ──► ApiExplorer           │
│    loadAndResolveSpec    │     │    ├── Authorization (Redux)       │
│    ├── Redocly bundle    │     │    ├── ParamOptions (Redux)        │
│    ├── $RefParser deref  │     │    ├── Body (Redux)                │
│    └── swagger2openapi   │     │    ├── Server selector             │
│                          │     │    ├── CodeSnippets (Postman)      │
│  processOpenapiFiles     │     │    ├── Request + Response          │
│    ├── markdown/*        │     │    └── SchemaItem / StatusCodes    │
│    └── sidebars/*        │     │                                    │
│                          │     │  Styling: SCSS + CSS modules       │
│  Output:                 │     │  State: @reduxjs/toolkit           │
│    *.api.mdx             │     │  Persistence: sessionStorage /     │
│    *.info.mdx            │     │    localStorage middleware         │
│    *.tag.mdx             │     └──────────────────────────────────┘
│    schemas/*.schema.mdx  │
│    sidebar.ts            │
│    versions.json         │
│    *.json (externalized) │
└─────────────────────────┘

┌──────────────────────────────┐
│  create-docusaurus-openapi   │
│  (Scaffolder CLI)            │
│  npx create-docusaurus-      │
│    openapi-docs <name>       │
│  Copies template + installs  │
└──────────────────────────────┘

Component Inventory

Note

The plugin operates exclusively at build time — it reads spec files and writes MDX/JSON. The theme operates at runtime — it renders the interactive explorer in the browser. There is no server-side component; API requests are made directly from the user's browser.

Technology Stack

Data Flow: Spec → MDX → Interactive Page

1. Spec Loading: readOpenapiFiles() reads the spec from file or URL
2. Bundling: @redocly/openapi-core bundles and resolves external $refs
3. Dereferencing: @apidevtools/json-schema-ref-parser fully dereferences all $ref pointers
4. Circular Handling: Custom serializer() replaces circular references with circular() markers
5. Swagger Conversion: If the spec has a swagger field, swagger2openapi converts it to OpenAPI 3.0
6. Processing: processOpenapiFiles() splits into API, Info, Tag, and Schema page metadata
7. Markdown Generation: Each page type gets its markdown from create*PageMD() functions
8. Externalization: When externalJsonProps is enabled, large JSON is written to separate .json files
9. MDX Rendering: Mustache renders the final MDX with frontmatter (including compressed API JSON)
10. Sidebar Generation: generateSidebarSlice() produces the sidebar.ts TypeScript file
11. Build: Docusaurus compiles MDX → React components
12. Runtime: ApiItem creates a Redux store per page, ApiExplorer renders the interactive UI

2. System Requirements

3. Configuration Reference

Plugin-Level Options

Per-API Config Options (under config.<id>)

Important

specPath and outputDir are the only truly required fields per API. All other options have sensible defaults. Note that outputDir should not have a trailing slash — the plugin strips it but consistent formatting avoids confusion.

Sidebar Options (under sidebarOptions)

Markdown Generator Options (under markdownGenerators)

Version Config Options (under versions.<versionId>)

Warning

The version key "all" is reserved and cannot be used as a version identifier. The plugin will emit an error: Can't use id 'all' for OpenAPI docs versions configuration key.

Theme Configuration (in themeConfig)

Environment Variables

4. Deployment & Scaling

Build Process

The monorepo build pipeline:

# Build all packages (plugin + theme)
yarn build-packages

# Build the demo site
yarn build-demo

# Or build everything
yarn build

Tip

During development, use yarn watch to rebuild packages on change, and yarn watch:demo with nodemon to auto-restart the demo dev server when package builds complete.

Production Build

# Generate API docs
npx docusaurus gen-api-docs all --all-versions

# Build static site
npx docusaurus build

# Serve locally to verify
npx docusaurus serve

The output is static HTML/JS/CSS in the build/ directory, deployable to any static hosting.

CI/CD Considerations

• Node.js requirement: >= 18 with native build tools (for sass compilation)
• Generation step: Run gen-api-docs before docusaurus build — the MDX files must exist
• Spec changes: Include a clean-api-docs + gen-api-docs step in CI to ensure fresh generation
• Cache: Clear .docusaurus/ cache between builds if specs change
• Large specs: Enable externalJsonProps: true (default) to avoid MDX compilation timeouts with large API specs

Note

The externalJsonProps feature writes large JSON to separate files loaded via require(), which can significantly reduce MDX compilation time. This is enabled by default since v5.0.

Firebase Deployment

The project includes Firebase configuration (.firebaserc, firebase.json) for deploying the demo site. The demo is hosted at https://docusaurus-openapi.tryingpan.dev.

5. Operations

Development Workflow

1. Clone the repository
2. Install dependencies:

yarn install

3. Build packages:

yarn build-packages

4. Start the demo:

yarn start

Tip

Use yarn watch in a separate terminal to auto-rebuild packages as you edit. The demo uses nodemon via yarn watch:demo to detect changes in packages/*/lib/.

Testing

# Unit tests (Jest)
yarn test

# Cypress integration tests (with dev server)
yarn test:cypress:dev

# Cypress tests (with built site)
yarn test:cypress

The test suite includes:

Note

Tests require NODE_OPTIONS=--experimental-vm-modules for Jest ESM support.

Release Process

1. Update package versions:

yarn release:version <major|minor|patch|premajor|preminor|prepatch|prerelease|graduate>

2. Generate changelog:

yarn release:changelog

3. Open a PR, get it merged

4. Publish to npm:

yarn release:publish

This creates a git tag and publishes all packages via Lerna.

Canary Releases

# Standard canary
yarn canary

# Beta canary
yarn canaryBeta

Canary versions use the format 0.0.0-<commit-count>+<short-hash> and are published to the canary npm tag.

Linting and Formatting

# Check formatting
yarn format

# Run ESLint
yarn lint

The project uses Prettier for formatting (via lint-staged + Husky pre-commit hook) and ESLint with TypeScript, React, and Cypress plugins.

6. Performance

MDX Compilation Optimization

Large OpenAPI specs can produce MDX files with megabytes of embedded JSON, causing slow compilation. The externalJsonProps feature (enabled by default) mitigates this by:

1. Extracting large JSON properties (params details, request schemas, status codes) into separate .json files
2. Loading them via require() in the MDX instead of inline embedding
3. Reducing MDX parse/compile time significantly

API JSON Compression

By default, the plugin compresses API JSON in MDX frontmatter using Node.js zlib.deflateSync() and base64 encoding. This reduces the size of generated MDX files. Set disableCompression: true to store JSON uncompressed (useful for debugging).

Build Performance Tips

• Use @docusaurus/faster (enabled in demo config via future.faster) for faster Docusaurus builds
• Avoid generating unnecessary API configs during development — use gen-api-docs <specific-id> instead of all
• Clean the .docusaurus/ cache if builds become slow after spec changes

7. Security

Credential Handling

The API explorer handles authentication credentials with configurable persistence:

The persistence middleware (persistenceMiddleware.ts) stores the Redux auth state using the configured storage backend. Keys are scoped by the API's info path.

Warning

When authPersistence is set to "localStorage", API keys and tokens persist in the browser's local storage. This is convenient for development but inappropriate for shared or public machines. Use "sessionStorage" (default) or false for production documentation sites where users log in with real credentials.

Request Credentials Policy

The requestCredentials option maps directly to the Fetch API's credentials option:

Credential Masking

Set maskCredentials: true per API to render auth input fields as password inputs (masked characters). This prevents shoulder-surfing in demo or presentation contexts.

Caution

The maskCredentials feature only masks the UI input. Credentials are still stored in browser storage (if authPersistence is enabled) and sent with each request. It is a UI-level convenience, not a security control.

CORS Proxy Security

When using proxy, all API requests are routed through the specified proxy server. The proxy receives the full request including authentication headers. Only use trusted proxies, and never route production API traffic through public CORS proxies.

Dependencies with Known Considerations

The project depends on crypto-js for potential hashing operations in the theme. The theme also uses pako for compression and buffer for binary data handling in the browser.

8. Developer Internals

Repository Structure

docusaurus-openapi-docs/
├── packages/
│   ├── docusaurus-plugin-openapi-docs/    # Build-time plugin
│   │   ├── src/
│   │   │   ├── index.ts                   # Plugin entry, CLI commands
│   │   │   ├── options.ts                 # Joi validation schema
│   │   │   ├── types.d.ts                 # Core TypeScript interfaces
│   │   │   ├── markdown/                  # 20+ MDX generators
│   │   │   │   ├── index.ts               # Barrel: createApiPageMD, createInfoPageMD, etc.
│   │   │   │   ├── createSchema.ts        # Schema → markdown rendering
│   │   │   │   ├── createStatusCodes.ts   # Response status code tables
│   │   │   │   ├── createParamsDetails.ts  # Parameter documentation
│   │   │   │   ├── utils.ts               # render(), externalization helpers
│   │   │   │   └── ...                    # 15+ more section generators
│   │   │   ├── openapi/                   # Spec processing
│   │   │   │   ├── index.ts               # readOpenapiFiles, processOpenapiFiles
│   │   │   │   ├── openapi.ts             # Core processing logic
│   │   │   │   ├── types.ts               # OpenAPI type definitions
│   │   │   │   ├── createRequestExample.ts
│   │   │   │   ├── createResponseExample.ts
│   │   │   │   ├── createSchemaExample.ts
│   │   │   │   └── utils/                 # Spec resolution and parsing
│   │   │   │       ├── loadAndResolveSpec.ts
│   │   │   │       ├── services/OpenAPIParser.ts
│   │   │   │       ├── services/RedocNormalizedOptions.ts
│   │   │   │       └── utils/             # JsonPointer, helpers, openapi utils
│   │   │   └── sidebars/                  # Sidebar generation
│   │   │       ├── index.ts               # generateSidebarSlice
│   │   │       └── utils.ts               # versionSelector, versionCrumb
│   │   └── package.json
│   │
│   ├── docusaurus-theme-openapi-docs/     # Runtime theme
│   │   ├── src/
│   │   │   ├── index.ts                   # Theme plugin: webpack config, paths
│   │   │   ├── types.d.ts                 # ThemeConfig, DocFrontMatter
│   │   │   ├── theme/
│   │   │   │   ├── ApiItem/               # Page-level component + Redux store
│   │   │   │   ├── ApiExplorer/           # Interactive API testing panel
│   │   │   │   │   ├── Authorization/     # Auth forms + Redux slice
│   │   │   │   │   ├── Body/              # Request body editor
│   │   │   │   │   ├── CodeSnippets/      # Postman code-gen integration
│   │   │   │   │   ├── ParamOptions/      # Parameter form items
│   │   │   │   │   ├── Request/           # HTTP request execution
│   │   │   │   │   ├── Response/          # Response display
│   │   │   │   │   ├── Server/            # Server URL selector
│   │   │   │   │   └── ...                # 10+ more sub-components
│   │   │   │   ├── Schema/                # Recursive schema renderer
│   │   │   │   ├── SchemaItem/            # Individual schema property
│   │   │   │   ├── StatusCodes/           # Response code display
│   │   │   │   └── ...                    # 15+ more theme components
│   │   │   └── markdown/                  # Client-side markdown utilities
│   │   └── package.json
│   │
│   └── create-docusaurus-openapi-docs/    # Site scaffolder
│       ├── src/index.ts                   # init() scaffolding logic
│       ├── templates/default/             # Template Docusaurus site
│       └── package.json
│
├── demo/                                  # Demo/docs site
│   ├── docusaurus.config.ts               # 9 API configurations
│   ├── sidebars.ts                        # Complex sidebar with versions
│   ├── customMdGenerators.ts              # Custom markdown generator example
│   └── examples/                          # OpenAPI spec files (Petstore, etc.)
│
├── cypress/                               # E2E tests
├── scripts/                               # Release, changelog, publishing
├── package.json                           # Root workspace config
├── lerna.json                             # Lerna monorepo config
├── tsconfig.base.json                     # Shared TypeScript config
└── jest.config.js                         # Jest configuration

Key Classes

OpenAPIParser (src/openapi/utils/services/OpenAPIParser.ts)

Central class for traversing and resolving OpenAPI schemas. Handles $ref pointer resolution, discriminator mapping, allOf/anyOf/oneOf merging, and circular reference detection. Uses a RefCounter helper to track dereferenced schemas.

JsonPointer (src/openapi/utils/utils/JsonPointer.ts)

RFC 6901 JSON Pointer implementation for navigating nested OpenAPI documents. Supports get(), set(), and compile()/parse() for path manipulation.

RedocNormalizedOptions (src/openapi/utils/services/RedocNormalizedOptions.ts)

Configuration normalization layer originally derived from Redocly. Provides defaults for rendering options like requiredPropsFirst, sortPropsAlphabetically, hideSchemaPattern, showWebhookVerb, minCharacterLengthToInitTextArea, and payloadSampleIdx.

Plugin Architecture Deep Dive

The plugin (pluginOpenAPIDocs) returns a Docusaurus plugin object with a single lifecycle hook: extendCli(). This registers four CLI commands:

1. gen-api-docs <id> — Main generation command

   • Resolves the spec via loadAndResolveSpec()
   • Processes into page metadata via processOpenapiFiles()
   • Generates sidebar via generateSidebarSlice()
   • Renders MDX via Mustache templates with markdown generators
   • Writes .api.mdx, .info.mdx, .tag.mdx, .schema.mdx, sidebar.ts, and externalized .json files

2. gen-api-docs:version <id:version> — Versioned generation

   • Merges version config with parent config
   • Generates versions.json with version metadata
   • Calls generateApiDocs() for the specified version

3. clean-api-docs <id> — Cleanup

   • Globs and deletes *.api.mdx, *.info.mdx, *.tag.mdx, sidebar.{js,ts}, *.json (except versions.json), and schemas/ directory

4. clean-api-docs:version <id:version> — Versioned cleanup

   • Cleans version-specific files and optionally versions.json

Note

The plugin does not overwrite existing MDX files. This is intentional — it allows users to manually edit generated files without losing changes. To regenerate, always clean first.

Theme Architecture Deep Dive

The theme plugin (docusaurusThemeOpenAPI) configures webpack with:

• SCSS support: Adds sass-loader rule (unless docusaurus-plugin-sass already provides one)
• Polyfills: Provides buffer, path-browserify, and process/browser for browser compatibility
• Theme paths: Points to lib/theme/ for compiled theme components

Redux State Management

Each ApiItem page creates an isolated Redux store (store.ts) with the following slices:

The persistenceMiddleware subscribes to auth state changes and persists them to the configured storage backend.

buildPostmanRequest.ts

Converts the Redux state (server URL, params, body, auth, headers) into a Postman Request object. This is used by postman-code-generators to produce code snippets and by makeRequest.ts to execute the actual HTTP call.

Markdown Generation Pipeline

The src/markdown/ directory contains 20+ generator functions, each responsible for one section of the MDX output:

The render() utility in utils.ts joins an array of markdown sections, filtering undefined entries. The runWithExternalization() function captures externalized JSON files during rendering.

Vendor Extension Support

The plugin recognizes these OpenAPI vendor extensions:

Supported Security Schemes

The Authorization component handles all OpenAPI 3.x security scheme types:

Generated File Types

9. Integration Points

Docusaurus Plugin Integration

The plugin integrates with @docusaurus/plugin-content-docs by:

1. Reading the routeBasePath and path from the docs plugin config (or preset) to correctly generate infoPath URLs
2. Using the docItemComponent: "@theme/ApiItem" setting to replace the default doc item renderer

When using presets like "classic", the plugin looks for docs config inside the preset's options. When using standalone @docusaurus/plugin-content-docs instances, it matches by plugin ID.

Multiple Plugin Instances

The plugin supports multiple instances for sites with separate API documentation sections:

plugins: [
  ["docusaurus-plugin-openapi-docs", {
    id: "core-api",
    docsPluginId: "classic",
    config: { /* ... */ },
  }],
  ["docusaurus-plugin-openapi-docs", {
    id: "admin-api",
    docsPluginId: "admin-docs",
    config: { /* ... */ },
  }],
],

When multiple instances exist, the CLI commands require --plugin-id to disambiguate.

Custom Sidebar Generators

The sidebarGenerators.createDocItem option allows full control over how API and schema items appear in the sidebar:

sidebarOptions: {
  sidebarGenerators: {
    createDocItem: (item, context) => ({
      type: "doc",
      id: item.id,
      label: item.title,
      className: `${item.method} api-method`,
      customProps: context.sidebarOptions.customProps,
    }),
  },
},

Spec Format Compatibility

Note

The plugin emits a console warning when converting Swagger 2.0: [ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0. This is informational and does not indicate an error.

CSS Theming

The demo includes 7 pre-built color palettes:

The PalettePicker component (demo/src/components/PalettePicker/index.tsx) allows runtime theme switching. The selected palette is persisted in localStorage under the openapi-demo-palette key, with a FOUC-prevention script injected via injectHtmlTags().

Theme components use SCSS (*.scss files alongside components) and CSS modules (*.module.css) for scoped styling.

Swizzling Theme Components

All theme components can be overridden via Docusaurus's swizzling mechanism:

npx docusaurus swizzle docusaurus-theme-openapi-docs ApiExplorer

The theme exports its TypeScript source path via getTypeScriptThemePath(), enabling --typescript swizzling.

10. Troubleshooting

Error: OpenAPI docs plugin ID '<id>' not found.

Cause: The --plugin-id flag references a plugin instance that doesn't exist.

Solution: Check your docusaurus.config.ts for the correct id value in the plugin configuration.

Error: OpenAPI docs plugin ID must be specified when more than one plugin instance exists.

Cause: Multiple docusaurus-plugin-openapi-docs instances exist but no --plugin-id was provided.

Solution: Pass -p <plugin-id> to specify which instance to target.

Note

This applies to all four CLI commands (gen-api-docs, gen-api-docs:version, clean-api-docs, clean-api-docs:version).

Error: ID '<id>' does not exist in OpenAPI docs config.

Cause: The API ID argument doesn't match any key in the config object.

Solution: Verify the API ID matches a key in config: { <id>: { ... } }.

Error: Can't use id 'all' for OpenAPI docs configuration key.

Cause: A config entry or version uses the reserved key "all".

Solution: Rename the config key to something other than "all".

Error: invalid HTTP code

Cause: An OpenAPI response uses an HTTP status code that isn't recognized.

Solution: Use standard HTTP status codes (200, 201, 400, etc.) or valid status code ranges (2XX, 4XX).

Error: Payload must have fields: ...

Cause: An OpenAPI object is missing required fields during processing.

Solution: Validate your OpenAPI spec for completeness. Common missing fields include type on schema objects and description on response objects.

Schema snapshot test failures

Cause: Changes to markdown generation functions produce different output.

Solution: Review the diff in src/markdown/__snapshots__/ and update snapshots if the changes are intentional:

yarn test -- --updateSnapshot

SASS compilation errors

Cause: The sass dependency failed to install native bindings.

Solution: Ensure you have native build tools installed (build-essential on Linux, Xcode CLI tools on macOS). If using Docker, use a Node.js image with native build support.

Warning

The theme automatically adds SCSS compilation rules to webpack unless docusaurus-plugin-sass is already configured. Having both can cause conflicts — install docusaurus-plugin-sass as a peer dependency and let it handle SCSS if you use it elsewhere in your site.

11. Reference

CLI Commands Summary

npm Scripts (Development)

Package Versions (as of source commit)