Redoc — Beautiful API Reference Documentation Generator

Introduction

Redoc renders OpenAPI specifications into clean, three-panel API reference documentation. The left panel shows a navigation menu, the center contains descriptions and schemas, and the right panel displays request and response examples. It produces documentation that is easy to read and navigate without requiring a backend.

What Redoc Does

• Generates responsive three-panel API documentation from OpenAPI 2.0 and 3.x specs
• Renders nested schemas with expand/collapse for complex object hierarchies
• Supports code samples in multiple languages via vendor extensions
• Produces a single static HTML file for easy hosting and distribution
• Offers a React component for embedding in existing web applications

Architecture Overview

Redoc is a React-based single-page application that parses an OpenAPI specification and renders it as a scrollable document. The navigation sidebar is generated from the spec's tags and operation paths. Schema rendering handles circular references, allOf/oneOf/anyOf compositions, and discriminators. The build output is a self-contained HTML file with inlined CSS and JavaScript.

Self-Hosting & Configuration

• Use the CLI to build a static HTML file from your spec: npx @redocly/cli build-docs spec.yaml
• Embed in any page with a single <redoc> tag and CDN script include
• Configure display options like hideDownloadButton, expandResponses, and requiredPropsFirst
• Add custom code samples using the x-codeSamples vendor extension in your spec
• Theme the output with the theme option to match your brand colors and typography

Key Features

• Three-panel layout with sticky navigation for large APIs
• Automatic schema rendering with nested object expansion
• Markdown support in descriptions for rich formatting
• Search functionality to find operations and schemas quickly
• Server-side rendering support for faster initial page loads

Comparison with Similar Tools

• Swagger UI — interactive with "Try it out" request execution; Redoc focuses on readable, static documentation
• Stoplight Elements — modular API docs components; Redoc is simpler to deploy as a single file
• Scalar — modern alternative with interactive features; Redoc has broader adoption for reference docs
• Slate — Markdown-based three-panel docs; Redoc generates automatically from OpenAPI specs
• ReadMe — hosted docs platform; Redoc is self-hosted and free

FAQ

Q: Can Redoc execute API requests like Swagger UI? A: No. Redoc is designed for reading documentation. For interactive testing, pair it with Swagger UI or use the Redocly developer portal.

Q: Does Redoc support OpenAPI 3.1? A: Yes. Redoc supports OpenAPI 2.0, 3.0, and 3.1 specifications.

Q: How do I add code samples to the documentation? A: Add the x-codeSamples vendor extension to operations in your spec with language and source fields.

Q: Can I customize the theme? A: Yes. Pass a theme object to configure colors, fonts, sidebar width, and typography throughout the documentation.

Sources

• https://github.com/Redocly/redoc
• https://redocly.com/redoc