Redoc

beginner

Beautiful API documentation from OpenAPI specs.

Overview

Redoc is an open-source tool developed by Redocly that generates beautiful, responsive API documentation from OpenAPI (formerly Swagger) specifications. Unlike interactive documentation tools, Redoc focuses on creating clean, professional-looking documentation with a three-panel layout that's perfect for public-facing API docs. The tool renders OpenAPI specs into static HTML with advanced features like code samples in multiple programming languages, nested object visualization, and mobile-responsive design. This Docker stack uses the official Redocly Redoc image running on nginx, configured to serve your OpenAPI specification as polished documentation. The setup mounts your OpenAPI JSON file directly into the container's web directory, where Redoc automatically renders it into comprehensive documentation. The configuration prioritizes simplicity and performance, making it ideal for teams who want to quickly publish professional API documentation without managing complex build processes. This stack is perfect for API developers, technical writers, and DevOps teams who need to publish clean, read-only API documentation for external developers or internal teams. Unlike Swagger UI's interactive approach, Redoc excels at creating documentation that looks more like traditional technical documentation while maintaining all the benefits of auto-generated content from your OpenAPI specs.

Key Features

Three-panel responsive layout with navigation, content, and code samples
Automatic generation of code samples in multiple programming languages (curl, JavaScript, Python, etc.)
Advanced OpenAPI 3.0 support including oneOf, anyOf, and complex schema relationships
Clean, professional styling optimized for public-facing documentation
Server-side rendering with no client-side JavaScript requirements for content display
Built-in search functionality across all documentation sections
Automatic deep-linking to specific operations and schema definitions
Mobile-responsive design that works well on tablets and smartphones

Common Use Cases

1Publishing public API documentation for SaaS platforms and web services
2Creating internal API documentation for microservices architectures
3Generating partner API documentation for B2B integrations
4Building developer portals with embedded API reference documentation
5Replacing manually maintained API documentation with auto-generated specs
6Creating print-friendly API documentation for compliance and audit requirements
7Hosting API documentation alongside CI/CD pipelines for automatic updates

Prerequisites

Valid OpenAPI 2.0 or 3.0 specification file in JSON or YAML format
Docker and Docker Compose installed on the host system
At least 64MB of available RAM for the nginx container
Port 8080 available on the host system (or modify the port mapping)
Basic understanding of OpenAPI specification structure and validation
Web server or reverse proxy knowledge if integrating with existing infrastructure

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  redoc: 
3    image: redocly/redoc:latest
4    container_name: redoc
5    restart: unless-stopped
6    environment: 
7      SPEC_URL: /spec/openapi.json
8    volumes: 
9      - ./openapi.json:/usr/share/nginx/html/spec/openapi.json:ro
10    ports: 
11      - "8080:80"

.env Template

.env

1# Mount your OpenAPI spec

Usage Notes

1Docs: https://redocly.com/docs/redoc/
2Access at http://localhost:8080 - clean three-panel layout
3Mount OpenAPI spec at /usr/share/nginx/html/spec/openapi.json
4Read-only documentation (no Try It Out button)
5Beautiful theming and code samples in multiple languages
6Better for public-facing docs than Swagger UI

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  redoc:
5    image: redocly/redoc:latest
6    container_name: redoc
7    restart: unless-stopped
8    environment:
9      SPEC_URL: /spec/openapi.json
10    volumes:
11      - ./openapi.json:/usr/share/nginx/html/spec/openapi.json:ro
12    ports:
13      - "8080:80"
14EOF
15
16# 2. Create the .env file
17cat > .env << 'EOF'
18# Mount your OpenAPI spec
19EOF
20
21# 3. Start the services
22docker compose up -d
23
24# 4. View logs
25docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/redoc/run | bash

Troubleshooting

Blank page or 'Spec not found' error: Verify the OpenAPI file path matches the volume mount and the file contains valid JSON/YAML syntax
Documentation renders but shows parsing errors: Validate your OpenAPI specification against the OpenAPI 3.0 schema using online validators or redoc-cli
Code samples not appearing for operations: Ensure your OpenAPI spec includes proper parameter definitions and request body schemas
Custom styling not applying: Redoc requires specific CSS overrides - mount custom stylesheets to the nginx html directory
Container fails to start with permission errors: Check file ownership and permissions on the mounted OpenAPI specification file
Performance issues with large specifications: Consider splitting large OpenAPI files into multiple smaller documentation sites or using Redoc's tag-based filtering

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

redoc

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download