Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 37 ยท Documentation Tools

Redoc and Static API Documentation

Build static OpenAPI documentation with Redoc and Redocly CLI, group tags, add code samples, compare Swagger UI, Redoc and Scalar, and see a Markdown generator stand-in.

Interactive tools such as Swagger UI are great for exploring, but many teams also want reference documentation that reads like a manual: a clean three-column page with a navigation tree, search, schema tables and code samples, delivered as one static HTML file. That is the niche of Redoc and the tools around it.

Redoc is an open-source renderer by Redocly. The tools below need Node and a browser, so they cannot run here. Commands are read-only; the generator at the end is a runnable Python stand-in that shows how documentation is derived from a spec.

Building a static page

With the Redocly CLI (@redocly/cli):

Terminal
# one self-contained HTML file
npx @redocly/cli build-docs openapi.yaml --output docs/index.html

# live preview with reload while you edit
npx @redocly/cli preview-docs openapi.yaml

The older redoc-cli package is deprecated in favor of @redocly/cli; new projects should use the latter. You can also embed the component into any page:

HTML
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
<redoc spec-url="/openapi.yaml"></redoc>

Because the output is a static file, you can host it on any web server, a CDN or GitHub Pages, with no backend.

Layout and features

Redoc's default layout has three panels: navigation on the left, descriptions and schemas in the middle, request and response examples on the right. Highlights:

  • Collapsible, searchable schema trees with constraints, enums and oneOf variants.
  • Response samples generated from example or schema.
  • Deep links for every operation and schema.
  • No Try it out button in the open-source version, which makes it safe to publish without worrying about live calls.

Vendor extensions Redoc understands

OpenAPI allows extra keys that start with x-. Redoc reads several:

YAML
info:
  title: Bookstore API
  version: 1.0.0
  x-logo:
    url: https://example.com/logo.svg
    altText: Bookstore

x-tagGroups:
  - name: Catalog
    tags: [Books, Authors]
  - name: Sales
    tags: [Orders, Payments]

paths:
  /books:
    get:
      tags: [Books]
      x-codeSamples:
        - lang: curl
          label: curl
          source: curl https://api.example.com/books

x-tagGroups creates top-level sections in the navigation, x-logo places your logo, and x-codeSamples shows hand-written examples next to each operation. Other tools ignore these keys, which is exactly how extensions are meant to work.

Comparing the main viewers

Tool Style Try it out Notes
Swagger UI Expandable operations Yes Most familiar; heavier for large specs
Redoc Three-panel reference Not in the open-source version Great reading experience, single file output
Scalar Modern two-panel, built-in client Yes Open source, themeable
Stoplight Elements Embeddable components Yes Good for developer portals
RapiDoc Web component Yes Many layout choices

Choose on audience: reference reading (Redoc), hands-on exploration (Swagger UI or Scalar). Many teams publish two views of the same spec.

Stand-in: generate Markdown docs from a spec

Documentation generators follow the same pattern as code generators: parse, group, render. The stand-in groups operations by tag, sorts them, and renders Markdown with a table of parameters.

Python Stand-in: render reference docs from a spec

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Real tools add schemas, examples, search and styling, but the structure is the same.

Publishing docs

  1. Lint the spec first (see linting with Spectral).
  2. Build the HTML in CI on every merge to the main branch.
  3. Deploy the file to static hosting and keep older versions at versioned URLs such as /docs/v1/.
  4. Link the raw openapi.yaml from the docs page so people can download it for their own tools.

Treat documentation like code: it is built from the spec in CI, reviewed in pull requests and versioned with the API. A page edited by hand will drift from the truth.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. What does x-tagGroups do in Redoc?

    It is a vendor extension that groups tags into navigation sections. Other tools simply ignore it.
  2. 2. Which package should new projects use to build Redoc docs?

    redoc-cli is deprecated; @redocly/cli provides build-docs and preview-docs.
  3. 3. Why is a static HTML docs page easy to host?

    The build output is a self-contained file, so any static host will do.

Summary

  • Redoc and similar tools produce readable reference docs as static files.
  • @redocly/cli build-docs builds a page; x-tagGroups, x-logo and x-codeSamples customize it.
  • Swagger UI suits exploring; Redoc suits reading; Scalar and others cover both.
  • Build docs in CI from a linted spec and keep versioned URLs.
  • The Python Markdown generator is a stand-in for the grouping and rendering logic.

Next: Writing great API descriptions