Redoc

Last reviewed Aug 26, 2026 · 732 words

One command gives you the whole product: npx @redocly/cli build-docs openapi.yaml produces a single self-contained HTML file with the three-panel reference layout that most commercial API docs copied. Host that file on anything that serves static assets and you have self-hosted Redoc. There is no database, no login, and nothing to update at 2 a.m. That zero-backend shape is why it is worth a page on a self-hosting site at all: the operational cost is the cost of a static file.

Static build or the serving container, but not both

The build route above is what I recommend. The output HTML embeds your spec and the renderer, so it works from an S3 bucket, a Caddy file server, a Gitea Pages-style setup, or a docs/ folder in your existing site. The alternative is the redocly/redoc image, which serves the renderer on port 80 and fetches the spec from a URL you set in SPEC_URL:

services:
  redoc:
    image: redocly/redoc
    environment:
      - SPEC_URL=https://api.example.com/openapi.json
    ports:
      - "8085:80"
    restart: unless-stopped

That version is right when the spec is generated live by the API itself (FastAPI, Spring, NestJS all publish one) and you want docs that never lag the code. The 256 MB in our catalogue is more than it will ever use. Pick the static build when the spec lives in git and goes through review; pick the container when the spec is a runtime artefact.

Lint before you render, or the page will lie

Redoc renders what it is given and is forgiving of a sloppy spec, which means broken $refs, missing response schemas, and undocumented parameters show up as blank panels rather than errors. Run npx @redocly/cli lint openapi.yaml in CI first. The default ruleset flags unused components, operations without descriptions, and missing operationIds, and the last of those is what powers Redoc's deep links, so a spec that passes lint gives you stable URLs for every endpoint. Twenty minutes of lint fixes is usually the difference between docs that look generated and docs that look written.

Read-only is a feature until it is not

The open-source renderer does not let readers send requests. There is no "Try it" button, no auth flow, no console. For an internal API that is exactly what you want: nobody accidentally hits production from a docs page. For a public API where you want people to make a first call in 30 seconds, it is a real gap, and Redocly's paid products are where that console lives. If interactive calls matter more to you than the layout, Swagger UI is the free tool that has them, and both render from the same OpenAPI 3.x file, so running one for the reference and the other for a sandbox is a reasonable answer.

Where it fits in a self-hoster's stack

The pattern I keep seeing in small teams: spec in the API repository, a CI job on the Git forge that lints and builds index.html, and the result pushed to a static host next to the rest of the docs. Docusaurus and similar site generators have Redoc plugins if you want the API reference inside a broader documentation site rather than as a lone page. Themed properly (the theme option in the build accepts colours, fonts, and logo), the output is indistinguishable from the docs of companies paying five figures a year for the hosted version.

Not a documentation platform, and not trying to be

It is not a documentation platform. There is no versioning across releases beyond building one HTML file per version, no search across multiple specs, and no comments. It is also not a design tool; the spec is authored elsewhere. Redoc's whole value is rendering, and it does that better than anything free in dev tools.

What I'd do

Keep the OpenAPI file in the API repo, lint it in CI, build one HTML file per tagged release with build-docs, and serve the lot from a static directory behind Caddy with a latest symlink. Add Swagger UI at a second path only if outside developers need a sandbox. Do not run a container for something a file can do.