Replacing Redoc with Scalar: Lessons in API Documentation UX

We made a mistake. Not a catastrophic one — the kind where you pick a reasonable tool, integrate it, and then discover through use that it doesn’t fit.

smplkit is API-first. Every product exposes RESTful APIs, and the API reference is one of the most important pages on the documentation site. We initially chose Redoc to render our OpenAPI specs. It’s a well-known, well-maintained project that produces beautiful three-panel API documentation.

It took about a week of integration work before we ripped it out and replaced it with Scalar.

What Went Wrong with Redoc

Redoc is a good product. Our problems were specific to how we were using it: embedded inside a VitePress documentation site with a dark theme.

Layout takeover. Redoc is designed to own the entire page. It renders its own sidebar, its own content area, and its own right-panel code samples. When you embed it inside a VitePress page that already has a sidebar and a top navigation bar, you get a site-within-a-site. The VitePress navigation sits above Redoc’s own navigation, creating a visually disjointed experience.

Dark theme resistance. Our documentation site uses a dark theme. Redoc has a dark theme too, but its internal CSS is deeply opinionated. The default light-themed sidebar rendered dark gray text on a black background — literally unreadable. Getting Redoc to match our color scheme required fighting its internal styles at every turn.

No interactivity. Redoc is read-only by design. You can browse endpoints, read descriptions, and see example payloads, but you can’t send a request. This is a deliberate product decision (they have a separate product for that), but it meant we needed a separate interactive playground — which was its own project.

Each of these problems has a workaround, but the workarounds compound. Custom CSS to override Redoc’s layout. Theme variables to fight the color scheme. A planned “Layer 2” playground that would need its own infrastructure. The integration complexity was disproportionate to the value.

Why Scalar

Scalar is an open-source OpenAPI documentation renderer built in Vue.js. We switched because it solved all three problems simultaneously:

Embeddable without layout takeover. Scalar’s CDN script loads inside a VitePress page with a dedicated full-width layout. The VitePress top navigation bar stays visible, and Scalar owns the content area below it. The result is a single coherent page, not a site-within-a-site.

Dark mode that works. Scalar exposes CSS variables (--scalar-*) for every color in its palette. Matching our documentation site’s dark theme was a straightforward CSS file, not a battle against internal styles. The pre-built themes (moon, kepler, saturn) gave us a starting point, and the variable overrides let us fine-tune from there.

Built-in interactive client. Scalar includes a “Try It” panel where developers can authenticate with an API key and execute real requests directly from the documentation. This eliminated the planned separate playground entirely — one layer instead of two.

The Integration Pattern

The API reference page uses Scalar’s CDN script inside a VitePress page with a dedicated layout. This pattern:

• Avoids SSR compatibility issues (Scalar renders client-side only)
• Keeps the VitePress top navigation bar for cross-site navigation
• Gives Scalar full control of the API reference content area
• Allows CSS variable overrides for theme matching

This is the same pattern used by platforms like Stripe and Twilio: the API reference is visually consistent with the surrounding documentation but has its own specialized layout for endpoint browsing and testing.

The OpenAPI spec is fetched live from the deployed backend at app.smplkit.com/api/v1/openapi.json. When API endpoints change, the documentation updates automatically — no rebuild required.

Architecture Simplification

The original plan had three documentation layers:

1. API Reference (Redoc) — read-only endpoint documentation
2. Interactive Playground — a separate app for testing API calls
3. Raw OpenAPI Spec — the machine-readable JSON for tooling

Scalar collapsed layers 1 and 2 into a single component. The revised architecture has two layers:

1. API Reference with built-in testing (Scalar) — browse and execute
2. Raw OpenAPI Spec — for Postman imports, SDK generation, and CI contract testing

One fewer system to build, deploy, and maintain. For a small team, eliminating an entire layer of architecture is a meaningful win.

Lessons for Choosing Documentation Tools

Test the embedding story, not just the standalone demo. Redoc’s standalone demo is beautiful. The problems only appeared when we embedded it inside our existing site. If your documentation renderer needs to coexist with other content, test that integration before committing.

Dark theme support is binary. A tool either supports your theme cleanly or it doesn’t. “Supports dark mode” on a feature list means nothing if the implementation requires overriding fifty CSS rules. Look for CSS variable theming — it’s the signal that the tool was designed for customization, not just dark-mode-as-a-checkbox.

Interactivity isn’t optional for API docs. Developers evaluate APIs by calling them. If your documentation doesn’t let them try endpoints with real data, they’ll open Postman or curl anyway. Building interactivity into the reference page eliminates the friction of switching tools.

The smplkit API reference is live at docs.smplkit.com/api-reference. Try it out — the “Try It” client lets you execute requests directly from the docs.