ReDoc Express Middleware

2.1.3 verified Thu Apr 23 auth: no javascript

redoc-express is a lightweight Express middleware designed to serve interactive API documentation using the ReDoc UI from OpenAPI/Swagger specifications. The current stable version is 2.1.3, last published 6 months ago, indicating active maintenance. It provides a simple, single-middleware setup to integrate professional-grade API documentation into Node.js Express applications without requiring complex build tools. A key differentiator is its first-class TypeScript support with comprehensive type definitions, 100% test coverage, and compatibility with Node.js 6+ (ES5) and Express 4.x/5.x. It supports both OpenAPI 3.0+ and Swagger 2.0 specifications. The package focuses on ease of use, offering sensible defaults and extensive customization options via ReDoc's configuration, including built-in CSP nonce support for enhanced security.

Common errors

error Error: Cannot find module 'redoc-express' ↓

cause The 'redoc-express' package has not been installed or is not correctly linked in your project.

fix

Run npm install redoc-express or yarn add redoc-express in your project directory.

error Something went wrong... Failed to fetch ↓

cause The ReDoc UI could not fetch the OpenAPI specification from the `specUrl` provided. This often happens if the URL is incorrect, the server serving the spec is unreachable, or there are CORS issues.

fix

Verify that the specUrl points to a valid and accessible OpenAPI JSON/YAML file. Test the URL directly in your browser. Ensure your server is running and configured to serve the spec at that endpoint, and that CORS policies allow the ReDoc page to fetch it if hosted on a different domain.

error YAMLException: failed to parse YAML ↓

cause The OpenAPI specification provided is not valid YAML or contains syntax errors.

fix

Validate your OpenAPI specification using an online validator (e.g., Swagger Editor or Redocly CLI lint command) to identify and correct any syntax or structural errors before serving it.

Warnings

gotcha The `specUrl` option for `redoc-express` expects a publicly accessible URL to your OpenAPI specification, not a local file path. If your spec is a local file, you must serve it via another Express route or a static file server first. ↓

fix Ensure your OpenAPI spec (JSON or YAML) is served at an HTTP/HTTPS endpoint, and provide that URL to `redoc-express` via the `specUrl` option. For local files, create an Express route like `app.get('/openapi.json', (req, res) => res.sendFile('path/to/spec.json'));`

breaking Breaking changes in the underlying ReDoc library (which `redoc-express` uses) might affect the `redocOptions` configuration. While `redoc-express` API tends to be stable, the shape of the `redocOptions` object can change between major ReDoc versions. ↓

fix Always review the `redoc` library's release notes when updating `redoc-express` to check for changes in available options or their structure. Validate your `redocOptions` configuration against the latest `redoc` documentation.

gotcha Incorrect Content Security Policy (CSP) headers on your server might block ReDoc from loading external resources or executing inline scripts, leading to a blank page or errors in the console. `redoc-express` offers `nonce` support. ↓

fix If you have a strict CSP, ensure that the policy allows scripts from `cdn.jsdelivr.net` (or wherever ReDoc assets are loaded from) and permits the execution of the necessary inline scripts. Use the `nonce` option in `redoc-express` if your CSP requires nonces: `redoc({ ..., nonce: res.locals.cspNonce })`.

Install

npm install redoc-express

yarn add redoc-express

pnpm add redoc-express

Imports

redoc
wrong
```
import redoc from 'redoc-express';
```
correct
```
import { redoc } from 'redoc-express';
```
The main middleware function is a named export, not a default export.

redoc

wrong

const redoc = require('redoc-express');

correct

const { redoc } = require('redoc-express');

For CommonJS, use object destructuring as 'redoc' is a named export.

RedocOptions
```
import { RedocOptions } from 'redoc-express';
```
TypeScript users can import type definitions for configuring ReDoc options.

Quickstart

This quickstart sets up a basic Express server, serves a minimal OpenAPI 3.0 specification, and integrates `redoc-express` to display interactive API documentation at the '/docs' endpoint. It demonstrates passing configuration options to ReDoc for customization.

import express from 'express';
import { redoc } from 'redoc-express';
import path from 'path';

const app = express();
const port = process.env.PORT || 3000;

// A minimal OpenAPI spec for demonstration
const openApiSpec = {
  openapi: '3.0.0',
  info: {
    title: 'My Awesome API',
    version: '1.0.0',
    description: 'An example API to demonstrate redoc-express',
  },
  paths: {
    '/hello': {
      get: {
        summary: 'Says hello',
        responses: {
          '200': {
            description: 'A greeting message',
            content: {
              'application/json': {
                schema: {
                  type: 'object',
                  properties: {
                    message: { type: 'string' }
                  }
                },
                example: { message: 'Hello, World!' }
              }
            }
          }
        }
      }
    }
  },
  components: {
    schemas: {}
  }
};

// Serve the OpenAPI spec as a JSON file
app.get('/openapi.json', (req, res) => {
  res.json(openApiSpec);
});

// Mount the redoc-express middleware
app.use(
  '/docs',
  redoc({
    title: 'API Documentation',
    specUrl: '/openapi.json', // URL where your OpenAPI spec is served
    redocOptions: {
      theme: {
        colors: { primary: { main: '#607d8b' } },
        typography: {
          fontFamily: 'Montserrat, sans-serif'
        }
      }
    }
  })
);

// Basic route for the API itself
app.get('/hello', (req, res) => {
  res.json({ message: 'Hello, World!' });
});

app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
  console.log(`API Docs available at http://localhost:${port}/docs`);
  console.log(`API Endpoint: http://localhost:${port}/hello`);
});