ADR-012: Adopt Scalar for OpenAPI Reference & Interactive API Client
Status: Accepted
Date: 2026-04-17
Deciders: Vivek (CEO), Rajesh (CTO)
Supersedes: None
Related: SPEC-003 (repository architecture — declares schemas/openapi/aucert-api-v1.yaml as the API contract source-of-truth), .context/TECH_STACK.md (Docusaurus v3 as the docs platform), forthcoming SPEC-017 (Scalar integration implementation)
Context
Aucert's backend exposes REST APIs defined by OpenAPI 3.x contracts at
schemas/openapi/aucert-api-v1.yaml (internal) and
public/openapi-spec/aucert-api-v1.yaml (public, reserved for launch).
Docusaurus + Cloudflare Pages is the locked-in docs platform. We have two internal audiences today (engineering team + Vibhu) and one future audience (customers + AI coding agents consuming our API at Month 6–9 public launch).
We need a tool that:
- Renders the OpenAPI contract as a browsable reference
- Provides an interactive "Try it out" API client (replaces Postman for 80% of internal use cases and serves Vibhu without curl)
- Integrates with Docusaurus — no new self-hosted infrastructure
- Looks production-grade at public launch
- Supports OpenAPI 3.1 and auto-generates multi-language code samples
- Works with the existing Cloudflare Pages + Cloudflare Access wildcard
Decision
Adopt Scalar via the @scalar/docusaurus plugin, deployed to the
internal docs site (docs.aucert.dev) now, with the same configuration
pattern to be applied to the public site (docs.aucert.ai) at launch via
a separate SPEC.
Alternatives Considered
| Option | Rejected Because |
|---|---|
| Swagger UI | Dated visual. Weakens public launch impression. Not first-class Docusaurus integration. |
| Redoc / redocusaurus | Polished reference but no interactive API client. Forces continued Postman dependency. |
| docusaurus-openapi-docs (PaloAltoNetworks) | Mature, stable, MDX-based. Less polished UI, weaker API client. Retained as named fallback. |
| ReadMe / Mintlify / Stoplight (hosted SaaS) | Adds new vendor dependency and recurring cost. Fragments docs surface. Paywalls core features. |
Ktor ktor-swagger-ui at /api-docs on backend | Valid as a deferral strategy if Scalar decision were postponed. Rejected here because the Scalar work is being done now — interim step has 100% replacement rate and negative ROI. |
Consequences
Positive
- Single tool serves both internal dev loop and public launch — no re-platforming at Month 6–9.
- Zero new infrastructure: plugin ships via pnpm, renders at build time into existing Cloudflare Pages deployment.
- Built-in API client replaces Postman for most internal use cases.
- OpenAPI 3.1 native, future-proof.
- Multi-language client code samples support public SDK strategy
(
public/sdk-typescript,public/sdk-python). - Agent-friendly output (clean HTML, deep-linkable) — aids Quality Oracle positioning.
Negative
@scalar/docusaurusplugin is labeled beta as of Q1 2026. Accepted risk for internal use; mitigation plan documented below.- Scalar is an earlier-stage company than Redocly. Lower baseline stability guarantee than Redoc.
- Scalar's hosted SaaS has paywall tiers (not relevant — we self-host OSS).
Neutral
- Initial API spec served as static asset from Docusaurus
static/directory until backend is live. Will switch to live backend endpoint (api.aucert.dev/openapi.yaml) at backend deployment time.
Fallback Plan
If @scalar/docusaurus plugin breaks the Docusaurus build or renders
incorrectly in production:
- Level 1 (same day): Replace plugin with
@scalar/api-reference-reactcomponent in a custom Docusaurus page atsrc/pages/api-reference.tsx. Core Scalar renderer is stable; only the plugin wrapper is beta. ~10 LOC change. - Level 2 (same week): Migrate to
docusaurus-openapi-docs(PaloAltoNetworks). Generates MDX at build time. Stable. Accept loss of built-in API client.
Both fallbacks use the same OpenAPI source file — no spec changes required.
Effort & Timeline
Implementation: ~2 hours (single SPEC, single PR). See SPEC-017 (forthcoming).