# Redoc — Beautiful API Reference Documentation Generator

> An open-source tool that generates responsive, three-panel API reference documentation from OpenAPI specifications with zero configuration.

## Install

Save as a script file and run:

# Redoc — Beautiful API Reference Documentation Generator

## Quick Use
```bash
# CLI (generate static HTML)
npx @redocly/cli build-docs openapi.yaml -o docs.html

# Docker
docker run -p 8080:80 
  -e SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json 
  redocly/redoc

# Or embed via CDN script tag in any HTML page
```

## 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

---
Source: https://tokrepo.com/en/workflows/ccec8773-4384-11f1-9bc6-00163e2b0d79
Author: Script Depot