ReDoc Cheat Sheet

Overview

ReDoc is an open-source tool for rendering OpenAPI (Swagger) specifications into clean, responsive, three-panel API documentation. The left panel provides navigation, the center panel shows descriptions and parameters, and the right panel displays request/response examples. ReDoc produces documentation optimized for readability and developer experience.

ReDoc supports OpenAPI 2.0 and 3.0/3.1 specifications and can be deployed as a standalone HTML page, embedded in existing websites, as a React component, or generated as a zero-dependency static HTML file via its CLI.

Installation

CDN (Quick Start)

<!DOCTYPE html>
<html>
<head>
  <title>API Documentation</title>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <style>body { margin: 0; padding: 0; }</style>
</head>
<body>
  <redoc spec-url='https://api.example.com/openapi.json'></redoc>
  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>

npm

# Install CLI tool
npm install -g @redocly/cli

# Install React component
npm install redoc

Docker

docker run -p 8080:80 \
  -e SPEC_URL=https://petstore.swagger.io/v2/swagger.json \
  redocly/redoc

CLI Usage

# Preview documentation with live reload
npx @redocly/cli preview-docs openapi.yaml

# Build static HTML file (zero dependencies)
npx @redocly/cli build-docs openapi.yaml -o docs/index.html

# Build with custom options
npx @redocly/cli build-docs openapi.yaml \
  --output docs/index.html \
  --title "My API Documentation" \
  --disableGoogleFont

# Validate OpenAPI spec
npx @redocly/cli lint openapi.yaml

# Bundle multi-file spec into single file
npx @redocly/cli bundle openapi.yaml -o bundled.yaml

# Split a single-file spec into multiple files
npx @redocly/cli split openapi.yaml --outDir api/

Configuration

redocly.yaml

extends:
  - recommended

theme:
  openapi:
    hideDownloadButton: false
    hideHostname: false
    jsonSampleExpandLevel: 2
    showExtensions: true
    sortOperationsAlphabetically: false
    menuToggle: true
    pathInMiddlePanel: false

    generateCodeSamples:
      languages:
        - lang: curl
        - lang: Python
          label: Python
        - lang: JavaScript
          label: Node.js

    theme:
      colors:
        primary:
          main: '#1a73e8'
        http:
          get: '#6bbd5b'
          post: '#248fb2'
          put: '#9b708b'
          delete: '#e27a7a'

      typography:
        fontSize: '15px'
        fontFamily: '"Inter", sans-serif'
        headings:
          fontFamily: '"Inter", sans-serif'
        code:
          fontSize: '13px'
          fontFamily: '"JetBrains Mono", monospace'

      sidebar:
        width: '260px'
        backgroundColor: '#fafafa'

      rightPanel:
        backgroundColor: '#263238'
        textColor: '#ffffff'

Configuration Options

Option	Type	Default	Description
`hideDownloadButton`	boolean	`false`	Hide spec download button
`hideHostname`	boolean	`false`	Hide server hostname
`expandResponses`	string	`""`	Auto-expand responses
`requiredPropsFirst`	boolean	`false`	Show required props first
`sortPropsAlphabetically`	boolean	`false`	Sort properties alphabetically
`pathInMiddlePanel`	boolean	`false`	Show path in center panel
`jsonSampleExpandLevel`	number	`2`	Default JSON expansion depth
`menuToggle`	boolean	`true`	Enable menu toggle
`nativeScrollbars`	boolean	`false`	Use native scrollbars
`scrollYOffset`	number	`0`	Sticky header offset
`disableSearch`	boolean	`false`	Disable search

JavaScript API

Redoc.init(
  'https://api.example.com/openapi.json',
  {
    scrollYOffset: 50,
    hideDownloadButton: false,
    theme: {
      colors: { primary: { main: '#1a73e8' } },
      typography: { fontSize: '15px' },
    },
  },
  document.getElementById('redoc-container')
);

React Component

import { RedocStandalone } from 'redoc';

function ApiDocs() {
  return (
    <RedocStandalone
      specUrl="https://api.example.com/openapi.json"
      options={{
        scrollYOffset: 50,
        theme: {
          colors: { primary: { main: '#1a73e8' } },
          sidebar: { width: '260px' },
        },
        nativeScrollbars: true,
      }}
    />
  );
}

Advanced Usage

OpenAPI Extensions for ReDoc

# Custom code samples
paths:
  /users:
    get:
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET https://api.example.com/users \
              -H "Authorization: Bearer TOKEN"
        - lang: Python
          source: |
            import requests
            response = requests.get(
                "https://api.example.com/users",
                headers={"Authorization": "Bearer TOKEN"}
            )

# Custom tags grouping
x-tagGroups:
  - name: User Management
    tags:
      - Users
      - Roles

# Custom logo
info:
  x-logo:
    url: https://example.com/logo.png
    altText: My API Logo

Framework Integration

Express.js

const express = require('express');
const app = express();

app.get('/docs', (req, res) => {
  res.send(`
    <!DOCTYPE html>
    <html>
    <head><title>API Docs</title></head>
    <body>
      <redoc spec-url='/openapi.json'></redoc>
      <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
    </body>
    </html>
  `);
});
app.listen(3000);

FastAPI (Python)

from fastapi import FastAPI

app = FastAPI(
    title="My API",
    version="1.0.0",
    redoc_url="/docs",
)

Troubleshooting

Issue	Solution
Spec not loading	Verify URL is accessible and CORS headers are set
Fonts not loading	Use `disableGoogleFont` and provide custom fonts
Sidebar navigation broken	Check tags are defined on operations
Code samples not showing	Add `x-codeSamples` extension or enable `generateCodeSamples`
Schema display issues	Validate spec with `npx @redocly/cli lint`
Large spec slow to render	Split spec into smaller files
Custom theme not applying	Check YAML syntax; verify theme property paths
Search not working	Ensure `disableSearch` is not set to `true`