Migrate from Redoc to Outworx Docs

Redoc is one of the most popular open-source OpenAPI renderers — and that's exactly why teams hit a wall. The OSS version has no Try It playground, no AI chat, no analytics, no auto-sync. To get any of that you upgrade to Redocly Premium, which lands at enterprise pricing. If you've outgrown Redoc OSS but don't want to negotiate a Redocly contract, Outworx Docs is the obvious next step at $9–$19/mo.

This guide takes whatever you have today (Redoc OSS, Redocly CLI, or Redocly Reef-hosted) and lands it on Outworx Docs in about ten minutes.

Step 1 — Locate your spec (1 minute)

You almost certainly already have it. Redoc renders directly from an OpenAPI file — no proprietary format, no vendor-locked storage.

# Common locations
ls openapi.yaml openapi.json api/openapi.yaml docs/openapi.yaml 2>/dev/null

If your Redoc deployment uses Redocly's multi-file $ref convention, bundle to a single file:

npx @redocly/cli bundle openapi.yaml -o bundled.yaml

This is the cleanest part of migrating from Redoc — your source is already exactly what Outworx wants.

Step 2 — Upload to Outworx Docs (1 minute)

1. Sign up at docs.outworx.io. Free, no card.
2. New Project → name → slug. URL: yourslug.docs.outworx.io.
3. API Spec tab → Upload → drag in bundled.yaml (or your existing single file).

Docs go live. Every endpoint rendered, with a working Try It playground (the thing you couldn't get on Redoc OSS), code snippets in cURL / Fetch / Axios / Python, version switcher, and the option to enable AI chat.

Step 3 — Compare what changed visually (2 minutes)

Open both side by side: your old Redoc site and the new Outworx site. Specifically check:

• Endpoint pages — Outworx renders schema definitions in collapsible cards rather than Redoc's three-column layout. Most users find it scans better; some Redoc fans miss the dense view. Either way, every field your Redoc had is here.
• Code samples — Redoc supports x-codeSamples extensions in your spec. Outworx renders these natively for cURL/Fetch/Axios/Python and falls back to AI-generated examples for any language not in your spec.
• Auth flows — OAuth2, API key, bearer auth all render correctly. The Try It playground respects them and lets visitors paste credentials to make real calls.

If something looks off, check the OpenAPI source. Outworx is strict about spec conformance; Redoc was occasionally lenient about malformed $ref chains. Run npx @redocly/cli lint against your spec to catch issues.

Step 4 — Versions (2 minutes)

If your Redoc setup served multiple versions (typically as separate deploys: docs-v1.yourcompany.com and docs-v2.yourcompany.com), consolidate them into one Outworx project:

1. API Spec tab → New version
2. Upload each version's spec
3. Label as v1, v2, etc.
4. Mark the default

URLs become yourslug.docs.outworx.io/v1, yourslug.docs.outworx.io/v2 — version switcher visible on every page.

Step 5 — Custom domain (5 minutes)

If your Redoc was deployed at docs.yourcompany.com:

On Outworx (Business, $19/mo):

1. Settings → Custom domain → enter the domain
2. Copy the CNAME target

On DNS:

1. Update your existing CNAME (currently pointing at your Redoc host — Vercel, Netlify, S3, wherever)
2. Point it at Outworx's target
3. Cloudflare: DNS only (grey cloud)

SSL provisions in 1–5 minutes. Done.

Step 6 — SEO redirects if your old paths differ

Redoc's URL shape varies depending on how you deployed it:

• Self-hosted Redoc: usually /operation/listUsers or #operation/listUsers (anchor-based)
• Redocly Reef-hosted: /<api-name>/operations/listUsers
• Outworx: /endpoints/listUsers

If your old setup used hash-based anchors (#operation/listUsers), Google indexes those as fragments of the same page, and migration usually doesn't need redirects — your indexed page (/) still resolves and Google reindexes the new structure naturally.

If you used path-based URLs, set up redirects:

docs-old.yourcompany.com/operation/* → docs.yourcompany.com/endpoints/$1

Keep the old deploy alive for 30 days during the transition.

What you gain by leaving Redoc OSS

This is mostly a list of "things Redoc OSS doesn't have":

• Try It playground that works against your real API. Redoc OSS doesn't ship one. Redocly Premium has it.
• AI chat trained on your spec, on every public docs page (Pro and Business). No equivalent on either Redoc OSS or Redocly.
• Per-project MCP server — Claude, Cursor, Cline plug straight into your docs. No equivalent anywhere in the Redocly ecosystem.
• Auto-sync from spec URL on hourly / daily / weekly cadence. Redoc requires you to re-deploy on every spec change.
• Hosted analytics — paths, referrers, countries, browsers, devices, time series — included on Business. Redoc OSS has none; Redocly Premium has them as a paid add-on.
• Auth-protected docs. Password protection on private docs, included. Redoc OSS doesn't ship this; you'd build it yourself with a reverse proxy.
• Team seats with no per-seat billing. 3 on Pro, 10 on Business.

What you lose by leaving Redoc

Honest: you give up full control over the rendered HTML/CSS. Outworx is opinionated about layout and theming — you can pick brand colors and a theme variant on Business, but you can't ship arbitrary CSS or custom React components into the renderer the way you can when you npm install redoc. If you've built deep custom UI on top of Redoc, that work doesn't port.

For 95% of teams that's a feature, not a bug — but worth knowing.

After the migration

• Wire auto-sync: Auto-sync API Docs from GitHub Actions on Every Push
• Add MCP for AI assistants: Connect Your API Docs to Claude Desktop via MCP
• Run outworx-proxy on dev machines so the Try It playground works against localhost

Total time: about ten minutes if your spec is already a single bundled YAML, fifteen if you need to bundle a multi-file Redocly project first.

Start your migration →