Redoc — Clean API Documentation with Three-Panel Layout
In this tutorial, you will learn about Redoc. We cover key concepts, practical examples, and best practices to help you master this topic.
Redoc is an open-source tool that renders OpenAPI specifications into clean, responsive, three-panel documentation with a navigation sidebar, main content area, and request/response samples.
In this tutorial, you will learn how to set up Redoc, customize its appearance, configure advanced features, and deploy it as a static documentation site.
What You'll Learn
You will learn Redoc installation options, theming and customization, advanced configuration for large APIs, and how Redoc compares to Swagger UI for different use cases.
Why It Matters
Redoc produces the cleanest documentation output of any OpenAPI renderer. Its three-panel layout is ideal for reference documentation where developers need to browse endpoints quickly. Many top API providers use Redoc for their public documentation.
Real-World Use
DodaTech uses Redoc for public-facing API documentation on the developer portal. The clean layout and fast search help developers find endpoints quickly. The API console is handled separately by Swagger UI for interactive testing.
flowchart LR A[OpenAPI Spec] --> B[Redoc] B --> C[Navigation Panel] B --> D[Content Panel] B --> E[Code Samples] B:::current classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px
CDN Installation
The simplest way to use Redoc:
<!DOCTYPE html>
<html>
<head>
<title>DodaTech API Reference</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<redoc spec-url="/openapi.yaml"></redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>
NPM Installation
Embed Redoc in a Node.js application:
npm install redoc
const express = require("express");
const redoc = require("redoc-express");
const app = express();
app.get("/docs", redoc({
title: "DodaTech API Reference",
specUrl: "/openapi.yaml",
nonce: "", // CSP nonce if needed
redocOptions: {
theme: {
colors: {
primary: { main: "#ff6600" }
}
},
sortPropsAlphabetically: true,
hideDownloadButton: false,
expandResponses: "200"
}
}));
app.use(express.static("public"));
app.listen(3000);
React Component
Use Redoc as a React component:
import { RedocStandalone } from "redoc";
function ApiDocs() {
return (
<RedocStandalone
specUrl="https://api.dodatech.com/openapi.yaml"
options={{
theme: {
colors: { primary: { main: "#ff6600" } },
sidebar: { backgroundColor: "#f5f5f5" }
},
nativeScrollbars: true,
hideLoading: false
}}
/>
);
}
Theming and Customization
Redoc supports extensive theme customization:
const options = {
theme: {
colors: {
primary: { main: "#ff6600" },
success: { main: "#28a745" },
warning: { main: "#ffc107" },
error: { main: "#dc3545" },
text: { primary: "#333333" }
},
sidebar: {
backgroundColor: "#fafafa",
textColor: "#333",
activeTextColor: "#ff6600"
},
rightPanel: {
backgroundColor: "#263238",
textColor: "#e0e0e0"
},
typography: {
fontSize: "14px",
fontFamily: "Inter, sans-serif",
code: {
fontSize: "13px",
fontFamily: "Fira Code, monospace"
}
},
logo: {
gutter: "16px",
maxHeight: "48px"
}
},
sortPropsAlphabetically: true,
hideDownloadButton: false,
nativeScrollbars: false,
expandResponses: "all",
pathInMiddlePanel: true,
requiredPropsFirst: true
};
Advanced Configuration
const advancedOptions = {
// Tag grouping
tagGroups: [
{
name: "User Management",
tags: ["Users", "Authentication", "Profiles"]
},
{
name: "Content Operations",
tags: ["Documents", "Files", "Comments"]
}
],
// Schema expansion
expandResponses: "200,201",
expandSingleSchemaField: true,
// Search
searchField: {
minCharactersToTrigger: 2,
debounceTime: 300
},
// Behavior
hideSchemaTitles: false,
simpleOneOfType: true,
showObjectSchemaExamples: true,
// Performance for large APIs
lazyRendering: true,
maxResponseContentLength: 5000
};
Deploying as Static Site
Generate a static HTML file with Redoc CLI:
npx redoc-cli bundle openapi.yaml -o docs.html \
--options.theme.colors.primary.main="#ff6600" \
--options.expandResponses="200" \
--title "DodaTech API Reference"
# Watch mode for development
npx redoc-cli serve openapi.yaml --watch \
--port 8080 \
--options.theme.colors.primary.main="#ff6600"
Common Mistakes
No navigation grouping — Displaying all endpoints in a flat list. Use tagGroups to organize endpoints into logical sections.
Too much information expanded — Expanding all responses and schemas by default. Use expandResponses sparingly for large APIs.
Ignoring mobile responsiveness — Not testing on mobile devices. Redoc is responsive by default but verify on small screens.
No search configuration — Keeping default search settings. Configure search to trigger earlier for large APIs.
Missing custom fonts — Redoc looks best with a modern font. Configure typography to match your brand.
Practice Questions
- What are the three panels in Redoc's layout?
- How do you customize Redoc's theme colors?
- How do you group endpoints into sections in Redoc?
- What is the difference between Redoc and Swagger UI?
- How do you generate a static HTML file from Redoc?
Challenge
Create a fully branded Redoc deployment for a movie database API. Configure custom colors, font, and logo. Group endpoints into logical sections (Movies, Actors, Reviews, Authentication). Generate a static HTML file with the CLI and serve it from an Express server.
FAQ
Mini Project
Brand and deploy Redoc for a task management API. Customize the theme with your brand colors, configure tag groups for logical navigation, enable lazy rendering, serve it from a Docker container, and generate a static HTML bundle for offline distribution.
What's Next
In the next lesson, you will learn about Stoplight Elements, an embeddable web component for interactive API documentation.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro