feat(docs): replace Scalar with Redoc for /api/docs UI

[PierreBrisorgueil]

Summary

• Replaces @scalar/express-api-reference with redoc-express for the /api/docs UI.
• Spec assembly, guides loader, YAML merge, and /api/spec.json handler are unchanged — Redoc consumes the spec by URL instead of inline content.
• Equivalents for Scalar's hideModels behavior: hideDownloadButton, hideSchemaTitles, expandResponses: '200,201' passed via redocOptions.

Redoc is a mature, widely-used OSS lib (MIT) with a cleaner three-panel layout better suited to a consumer-facing API reference. No try-it-out panel, which this API does not need (API-key-gated, programmatic use).

Closes #3464

Changes

• package.json — @scalar/express-api-reference removed, redoc-express added
• lib/services/express.js — mount redoc({ title, specUrl, redocOptions }) via app.get('/api/docs', …) (redoc-express exposes a plain handler); comments updated
• lib/helpers/guides.js — comments updated (Scalar → Redoc); behavior unchanged
• modules/core/tests/core.integration.tests.js — describe('Redoc API reference', …) rename; assertions untouched
• modules/core/tests/core.unit.tests.js — adjust initSwagger mount assertion to match app.get('/api/docs', …)
• MIGRATIONS.md — "Redoc replaces Scalar" entry above the existing Scalar-replaces-swagger-ui block

Test plan

• npm run lint green
• npm run test:coverage — 769/769 passing, coverage thresholds unchanged
• Local smoke test — /api/docs returns 200 + text/html with Redoc container, script from unpkg.com/redoc@^2.5.2, Redoc.init("/api/spec.json", { hideDownloadButton, hideSchemaTitles, expandResponses })
• /api/spec.json still returns 200 + OpenAPI 3.0.0 with info.title / servers injected from config

Downstream impact

Zero. Each downstream project picks up the change via /update-stack — no project-side YAML, config, or CSP tweaks required.

[coderabbitai]

Warning

Rate limit exceeded

@PierreBrisorgueil has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 54 minutes and 23 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 54 minutes and 23 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: e6d47735-2e47-497b-a28f-40cef6ab6352

📥 Commits

Reviewing files that changed from the base of the PR and between fcfa5b1 and ed76007.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (6)

• MIGRATIONS.md
• lib/helpers/guides.js
• lib/services/express.js
• modules/core/tests/core.integration.tests.js
• modules/core/tests/core.unit.tests.js
• package.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/redoc-replace-scalar

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.82%. Comparing base (fcfa5b1) to head (ed76007).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #3466   +/-   ##
=======================================
  Coverage   85.82%   85.82%           
=======================================
  Files         115      115           
  Lines        2914     2914           
  Branches      807      807           
=======================================
  Hits         2501     2501           
  Misses        327      327           
  Partials       86       86           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR swaps the API docs UI at /api/docs from Scalar to Redoc while keeping the existing OpenAPI spec assembly and /api/spec.json endpoint unchanged.

Changes:

• Replace @scalar/express-api-reference with redoc-express.
• Update initSwagger to mount Redoc at /api/docs using specUrl: '/api/spec.json' and Redoc UI options.
• Update tests and migration notes to reflect the Redoc UI.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
package.json	Removes Scalar dependency and adds redoc-express.
package-lock.json	Updates lockfile to reflect dependency swap.
lib/services/express.js	Replaces Scalar middleware with Redoc handler mounted on /api/docs.
lib/helpers/guides.js	Updates comments referencing Scalar → Redoc (no functional change).
modules/core/tests/core.integration.tests.js	Renames Scalar docs test descriptions to Redoc.
modules/core/tests/core.unit.tests.js	Updates unit assertion to match /api/docs being mounted via app.get.
MIGRATIONS.md	Adds a migration entry documenting the UI swap for downstream projects.