API Reference Rendering Options designed
GPUaaS already syncs the canonical OpenAPI and AsyncAPI artifacts into the portal. The next question is how to render those contracts into a browsable developer reference without breaking the contract-first model.
Rendered reference is not the same as a GPUaaS API playground. See API Playground for the separate requirement to execute curated calls against mock, dev, sandbox, UAT, or partner environments.
Current State
| Area | Current portal behavior |
|---|---|
| OpenAPI | doc/api/openapi.draft.yaml is copied to /api/openapi.draft.yaml during docs-portal-check |
| Scalar OpenAPI copy | docs-portal-check also writes /api/openapi.scalar.yaml from the same source for the Scalar pilot |
| AsyncAPI | doc/api/asyncapi.draft.yaml is copied to /api/asyncapi.draft.yaml during docs-portal-check |
| Human guidance | Auth/access, idempotency, errors, events, and artifact links are portal-native pages |
| Generated rendering | Portal-native pilot route is available at REST Reference Pilot; full renderer selection remains open |
Candidate Options
| Option | Fit | Notes |
|---|---|---|
| Stoplight / Stoplight Elements | Strong candidate because GPUaaS already uses Stoplight in product/API workflows | Good fit for OpenAPI-first design and product familiarity. Stoplight has Try It support, but GPUaaS still needs to decide whether that mode is mock-backed or live/sandbox-backed in our implementation. |
| Scalar Docusaurus integration | Strong candidate if we want a polished embedded API reference/playground and are willing to switch tooling | Scalar provides an @scalar/docusaurus plugin that renders an API reference at a Docusaurus route from an OpenAPI URL or multiple sources. Needs a local pilot against /api/openapi.draft.yaml. |
| Docusaurus OpenAPI Docs | Strong fit for REST reference generated from OpenAPI into Docusaurus-native MDX pages | The Palo Alto Networks project generates MDX from OpenAPI and pairs with a Docusaurus theme. It supports Docusaurus v3 and the current 5.x line targets Docusaurus 3.10+. |
| Embedded Redoc/Swagger-style viewer | Good short-term fit for a single interactive OpenAPI page | Lower integration work, but usually less native to Docusaurus navigation and versioned docs. |
| Scalar-style embedded reference | Good developer UX option to evaluate | Useful if we want a polished API explorer surface, but still needs security review for auth/request behavior. |
| Static artifact links only | Safe baseline | Already implemented; insufficient as the final developer portal experience. |
| Custom generated MDX | Maximum control | Highest ownership cost; only worth it if existing tools cannot satisfy our source, security, and navigation needs. |
Decision Criteria
| Criterion | Requirement |
|---|---|
| Contract authority | Generated pages must come from doc/api/openapi.draft.yaml and doc/api/asyncapi.draft.yaml, not hand-authored endpoint copies |
| Build determinism | make docs-portal-check must regenerate or validate rendered output locally and in CI |
| Navigation fit | Generated REST reference should sit under Developer APIs without overwhelming audience-first docs |
| Security posture | Try-it-out, auth persistence, proxies, request credentials, and masking behavior must be reviewed before enabling interactive calls |
| Product fit | Stoplight is already familiar in the product workflow, so reuse is valuable if it can be embedded cleanly in the portal |
| Switching cost | A better developer experience can justify switching, but only if the renderer integrates cleanly with Docusaurus, contracts, publication tracks, and playground security controls |
| Versioning path | The tool should handle future public/customer/partner/internal tracks and versioned API references |
| AsyncAPI story | OpenAPI rendering does not solve event reference rendering; AsyncAPI needs a matching plan |
| Source-doc metadata | Portal pages around the generated reference must continue to list canonical source_docs |
Recommended Path
- Keep the current static artifact sync as the baseline.
- Compare Stoplight/Elements, Scalar, and Docusaurus OpenAPI Docs against the same synced OpenAPI artifact.
- Add a small pilot for OpenAPI rendering in a separate route, for example
/developer-apis/rest-reference-pilot. - Disable live request execution until security and environment routing are reviewed.
- Keep generated output out of manual edits; regenerate from the synced contract.
- Evaluate an AsyncAPI rendering path separately so event consumers get the same quality of reference.
Stoplight-Specific Notes
Stoplight should be evaluated first because the product already uses it. The decision is not simply "does Stoplight render OpenAPI?" It does. The GPUaaS decision is whether the implementation gives developers a smooth portal-native experience:
| Question | Why it matters |
|---|---|
| Can the rendered reference live inside the Docusaurus developer path? | Keeps developer docs, App SDK guidance, and API reference in one journey |
| Does our integration expose try-it on the page, or does it send users elsewhere? | In-page execution is useful for developers, but must be security reviewed |
| Can try-it be disabled by environment or publication track? | Public/customer docs may need safer defaults than internal docs |
| Can auth persistence and request credentials be configured safely? | Prevents leaking tokens or encouraging unsafe browser flows |
Can generated output be tied to docs-portal-check? | Keeps the reference from drifting from doc/api/openapi.draft.yaml |
See Stoplight Elements Research for the current spike result and pilot shape.
Scalar-Specific Notes
Scalar should be evaluated as a possible switch if its Docusaurus integration
gives us a better developer experience than our current Stoplight usage. The
Docusaurus integration installs as @scalar/docusaurus, registers a plugin
route, and points its configuration at an OpenAPI URL or multiple API sources.
| Question | Why it matters |
|---|---|
Can Scalar consume /api/openapi.draft.yaml from the synced portal artifact? | Keeps contract authority in doc/api/openapi.draft.yaml |
Can it be embedded at /developer-apis/rest-reference without disrupting the audience-first sidebar? | Keeps API reference inside the developer journey |
| Does the playground support the environment/credential controls defined in API Playground? | Avoids adopting a nice renderer that cannot become our real playground |
| Can live execution be disabled for public/customer tracks while enabled for internal sandbox tracks? | Needed for publication safety |
| Does it work with Docusaurus 3.10.1, TypeScript config, and pnpm in our repo? | Reduces integration risk |
See Scalar Research for the current spike result and proposed side-by-side pilot with Stoplight.