Skip to content

Redoc — Beautiful Static API Documentation from OpenAPI

DodaTech Updated 2026-06-28 2 min read

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 generates beautiful, responsive static documentation pages from OpenAPI specifications with a clean three-panel layout.

What You'll Learn

  • Generating Redoc documentation
  • Customizing Redoc branding
  • Hosting Redoc on GitHub Pages, Netlify, or CDN

Why It Matters

Redoc produces cleaner, more readable documentation than Swagger UI for non-interactive use. Many APIs serve Redoc for reading and Swagger UI for testing.

Code Examples

<!-- Redoc standalone HTML -->
<!DOCTYPE html>
<html>
<head>
  <title>API Reference</title>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
  <div id="redoc-container"></div>
  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js">
  </script>
  <script>
    Redoc.init(
      '/openapi.yaml',
      {
        scrollYOffset: 50,
        hideDownloadButton: false,
        expandResponses: '',
        requiredPropsFirst: true,
        sortPropsAlphabetically: true,
        showObjectSchemaExamples: true,
        theme: {
          colors: {
            primary: { main: '#2563eb' }
          },
          typography: {
            fontFamily: 'Inter, sans-serif'
          }
        }
      },
      document.getElementById('redoc-container')
    );
  </script>
</body>
</html>

# Generate static Redoc HTML from CLI
npx redoc-cli bundle -o docs/index.html openapi.yaml

# With custom options
npx redoc-cli bundle -o docs/index.html \
  --title "Durga API Reference" \
  --options.theme.colors.primary.main "#2563eb" \
  openapi.yaml

# Serving Redoc with FastAPI
from fastapi import FastAPI
from fastapi.openapi.docs import get_redoc_html

app = FastAPI()

@app.get("/redoc", include_in_schema=False)
async def redoc_html():
    return get_redoc_html(
        openapi_url="/openapi.json",
        title="Durga API Reference",
        redoc_favicon_url="/favicon.ico"
    )

Common Mistakes

1. Using Redoc Without Try-It-Out

Redoc is read-only. Serve Swagger UI alongside for testing.

2. Not Customizing Theme

Default Redoc is generic. Customize colors and logo for branding.

3. Large Spec Performance

Redoc loads the entire spec at once. Very large specs may be slow.

4. Missing Mobile Responsiveness Check

Redoc is responsive by default, but verify on mobile devices.

5. Not Publishing Search Index

Redoc's built-in search only works on loaded content.

Practice Questions

  1. What is the main difference between Redoc and Swagger UI?
  2. How do you customize Redoc's primary color?
  3. Can Redoc be used without internet?
  4. How do you generate a static HTML file from Redoc CLI?
  5. What is a common deployment pattern for Redoc?

Answers:

  1. Redoc is read-only documentation; Swagger UI is interactive.
  2. Through the theme.colors.primary.main option.
  3. Yes, by Bundling to a static HTML file with redoc-cli.
  4. Using npx redoc-cli bundle openapi.yaml.
  5. Generate static HTML and deploy to CDN, GitHub Pages, or Netlify.

Challenge: Generate Redoc documentation for an OpenAPI spec, customize the theme to match your brand colors, and deploy the static HTML to GitHub Pages.

FAQ

Is Redoc free?

: Yes. Redoc is open source with a premium hosted version available.

Can I add custom content between endpoints?

: Use x-tags or the Redoc vendor extension for custom sections.

Does Redoc support OpenAPI 3.1?

: Yes. Redoc supports OpenAPI 3.0 and 3.1.

← Previous Swagger UI — Interactive API Documentation from OpenAPI Specs Next → Stoplight — Collaborative API Design and Documentation Platform

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Api Documentation