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

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

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