Replacing Redoc with Scalar: lessons in API documentation UX
We made a mistake. The kind where you pick a reasonable, well-maintained tool, spend a week integrating it, and discover through use that it doesn’t fit.
smplkit is API-first — every product exposes a REST API, and the API reference is one of the most important pages on the docs site. We chose Redoc to render our OpenAPI specs, because Redoc is a known quantity that produces beautiful three-panel documentation. A week of integration later, we ripped it out and replaced it with Scalar.
What went wrong with Redoc
Redoc is a good product. Our problem was the situation we put it in: embedded inside a VitePress documentation site with a dark theme.
Layout takeover. Redoc is designed to own the entire page — its own sidebar, its own content area, its own code-sample panel. Embed it in a VitePress page that already has a sidebar and top navigation, and you get a site-within-a-site, two navigation systems stacked on top of each other.
Dark theme resistance. Redoc has a dark theme, but its internal CSS is deeply opinionated, and our docs site is dark. The default light-themed sidebar rendered dark gray text on a black background — literally unreadable — and getting Redoc to match our palette meant fighting its internals rule by rule.
No interactivity. Redoc is read-only by design; they offer a separate product for trying requests. That’s a legitimate product decision on their side, but for us it meant a whole second project: a standalone interactive playground.
Each problem has a workaround. The workarounds compound: override CSS for the layout, more overrides for the theme, and an entire planned second application for interactivity. The integration complexity was out of all proportion to what we were getting.
Why Scalar
Scalar is an open-source OpenAPI renderer that happened to dissolve all three problems at once.
It embeds without taking over: the CDN script loads inside a VitePress page with a dedicated full-width layout, the VitePress top nav stays for cross-site navigation, and Scalar owns the content area below. One coherent page. Its theming is CSS variables — --scalar-* for every color in the palette — so matching our dark theme came down to one CSS file; the built-in themes gave us a starting point and the variables did the fine-tuning. And it ships a “Try It” panel where a developer can paste an API key and execute real requests from inside the reference, which deleted the separate-playground project from the roadmap entirely.
The OpenAPI spec is fetched live from the deployed backend at app.smplkit.com/api/v1/openapi.json, so when endpoints change, the reference updates with no rebuild.
One layer instead of two
The original documentation plan had three layers: Redoc for read-only reference, a separate interactive playground, and the raw OpenAPI JSON for tooling. Scalar collapsed the first two, leaving reference-with-testing plus the raw spec (which stays, for Postman imports, SDK generation, and CI contract tests). For a small team, deleting an entire system from the architecture diagram is about the best outcome an integration decision can have.
Lessons for choosing documentation tools
Test the embedding story, not the standalone demo. Redoc’s demo is gorgeous. Our problems only existed inside our site. If your renderer has to coexist with existing navigation and theming, evaluate it there, before committing a week to it.
Dark theme support is binary. Either the tool exposes its colors for you to set, or “supports dark mode” is a checkbox that costs you fifty CSS overrides. CSS-variable theming is the tell that customization was designed in.
Interactivity isn’t optional for API docs. Developers evaluate APIs by calling them. If the reference can’t execute a request, they’ll go do it in Postman or curl — and now your beautiful documentation is a tab they left.