redoc-express

redoc-express

Lightweight Express middleware for serving interactive ReDoc API documentation from OpenAPI/Swagger specs with full TypeScript support and zero configuration overhead.

Features

• 🚀 Lightweight & Fast - Minimal overhead, serves static documentation
• 📝 Full TypeScript Support - First-class TypeScript support with complete type definitions
• ✅ 100% Test Coverage - Comprehensive test suite with 136 test cases covering all functionality
• 🎨 Customizable UI - Full ReDoc theming and configuration support
• 🔒 Secure - Built-in CSP nonce support for enhanced security
• 📦 ES5 Compatible - Works across all Node.js versions (Node 6+)
• 🔧 Zero Config - Works out of the box with sensible defaults
• 🧩 OpenAPI/Swagger - Support for both OpenAPI 3.0+ and Swagger 2.0 specifications

Why redoc-express?

redoc-express makes it dead simple to add professional API documentation to your Express server. Unlike alternatives:

• No build tools required
• Single middleware setup
• Works with your existing OpenAPI/Swagger spec
• Highly customizable but requires no configuration to get started
• Production-ready with 100% code coverage and 136 comprehensive tests

Demo

• Live Demo
• Product Website

Quick Start

Install

npm install redoc-express

Usage

JavaScript/CommonJS

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

const app = express();
const port = 3000;

// Serve your OpenAPI/Swagger spec
app.get('/docs/swagger.json', (req, res) => {
  res.sendFile('swagger.json', { root: '.' });
});

// Mount ReDoc middleware
app.get(
  '/docs',
  redoc({
    title: 'API Documentation',
    specUrl: '/docs/swagger.json'
  })
);

app.listen(port, () => {
  console.log(`📚 API docs available at http://localhost:${port}/docs`);
});

TypeScript

import express, { Express } from 'express';
import redoc from 'redoc-express';

const app: Express = express();
const port = 3000;

// Serve your OpenAPI/Swagger spec
app.get('/docs/swagger.json', (req, res) => {
  res.sendFile('swagger.json', { root: '.' });
});

// Mount ReDoc middleware with TypeScript support
app.get(
  '/docs',
  redoc({
    title: 'API Documentation',
    specUrl: '/docs/swagger.json',
    redocOptions: {
      theme: {
        colors: {
          primary: { main: '#1976d2' }
        }
      }
    }
  })
);

app.listen(port, () => {
  console.log(`📚 API docs available at http://localhost:${port}/docs`);
});

Advanced Configuration

app.get(
  '/docs',
  redoc({
    title: 'My API Documentation',
    specUrl: 'https://api.example.com/openapi.json',
    nonce: 'random-nonce-123', // Optional: for CSP compliance
    redocOptions: {
      theme: {
        colors: {
          primary: { main: '#6EC5AB' }
        },
        typography: {
          fontFamily: '"museo-sans", Helvetica, Arial, sans-serif',
          fontSize: '15px'
        },
        menu: { backgroundColor: '#ffffff' }
      },
      hideDownloadButton: true,
      expandResponses: '200,201,400'
    }
  })
);

For all available ReDoc configuration options, see the official documentation

Configuration Options

Option	Type	Required	Description
title	string	Yes	Title displayed in the browser tab and header
specUrl	string	Yes	URL to your OpenAPI/Swagger specification file
nonce	string	No	Security nonce for Content Security Policy compliance
redocOptions	object	No	ReDoc configuration options

Compatibility

• Node.js: 6+ (ES5 compatible)
• Express: 4.x, 5.x
• OpenAPI: 3.0+, Swagger 2.0
• TypeScript: 3.5+

Development

Install Dependencies

npm i

Run Tests

npm test

Build

npm run build

Test Coverage

Coverage Metrics

Metric	Coverage
Statements	100%
Branches	100%
Functions	100%
Lines	100%

Test Suite

136 comprehensive test cases organized across 3 test suites:

• Unit Tests - redocHtml (85+ tests)

  • HTML structure and DOCTYPE validation
  • Title handling (unicode, emoji, special characters, extreme lengths)
  • URL/Spec handling (protocols, authentication, fragments, long URLs)
  • Nonce validation and CSP compliance
  • ReDoc options configuration (objects, arrays, numbers, booleans)
  • JSON serialization and escaping

• Unit Tests - redocExpressMiddleware (51+ tests)

  • Express middleware behavior and method ordering
  • Content-type and response handling
  • Request/response immutability
  • Multiple middleware invocations
  • Edge cases and error handling

• End-to-End Tests (26+ tests)

  • Real-world Express integration scenarios
  • Concurrent request handling
  • Multiple API documentation versions
  • Route isolation and middleware chains
  • Stress testing with rapid requests

Test Execution

npm test              # Run all 136 tests
npm test -- --coverage # With coverage report
npm test -- --watch   # Watch mode during development

All tests pass with 100% code coverage in approximately 1-2 seconds.

FAQ

Q: Can I use this with TypeScript? A: Yes! Full TypeScript support with included type definitions.

Q: Does this work with OpenAPI 3.0? A: Yes, both OpenAPI 3.0+ and Swagger 2.0 are supported.

Q: Is there a performance impact? A: Minimal. The middleware only serves static HTML—no runtime overhead.

Q: Can I customize the UI colors/fonts? A: Yes, pass redocOptions with your theme configuration.

Q: What Node.js versions are supported? A: Node 6+ (ES5 compiled output). Development requires Node 18.14+.

Resources

• ReDoc Documentation
• OpenAPI Specification
• Report Issues

License

MIT © Aung Myo Kyaw