Embedded API docs

SaaS products ship a machine-readable API contract. The modern standard is OpenAPI 3.x (successor to Swagger 2.0). This page embeds both formats with Swagger UI — the reference viewer that supports legacy Swagger 2.0 and current OpenAPI 3 specs.

In-page API reference (Swagger UI)

OpenAPI 3.0 (recommended)

Spec: /specs/connect-api.openapi.yaml — same fictional Connect subset as the PoC.

Swagger 2.0 (legacy)

Spec: /specs/connect-api.swagger.json — equivalent paths for teams still on Swagger 2.0 tooling.

Naming

OpenAPI 3 is the current specification (YAML/JSON). Swagger 2.0 is the older format (swagger: "2.0", definitions instead of components/schemas). Swagger UI is the interactive viewer — it renders both.

Other embed options (comparison)

Swagger UI (this page)

• Pros: Familiar “Try it out”, models, filters; supports OpenAPI 3 and Swagger 2.0; single <OpenApiEmbed> component (swagger-ui-dist).
• Cons: Heavier bundle than read-only viewers; style is Swagger-branded (lightly themed in starlight.css).

Redoc

• Pros: Clean read-only layout, fast scanning.
• Typical setup: Redoc CDN or @redocly/cli static HTML — good when you do not need try-it-out.

Scalar / Stoplight

• Pros: Modern try-it-out, theming, monetization-friendly portals.
• Typical setup: Hosted portal or React embed package.

Generated sidebar

• Pros: One operation per URL, deep links, search — e.g. community plugins or custom getStaticPaths from OpenAPI.
• Cons: More build pipeline; best for large APIs.

CORS and secrets

“Try it out” against real environments needs CORS, OAuth, and often a sandbox base URL. Pass tryItOut={true} on <OpenApiEmbed> only on internal or authenticated doc pages. This demo keeps try-it-out disabled on public pages.

Link-out pattern (production)

The gated Connect API reference page uses link-out to the live v5 docs — a valid pattern when reference is maintained elsewhere.

Authoring checklist

1. Publish OpenAPI 3 under public/specs/ (generate from code or design-first).
2. Keep a Swagger 2.0 export only if downstream tools still require it — prefer one source of truth (OAS3).
3. Version specs (connect-v1.yaml, v2.yaml) and link from changelog pages.
4. Pair every major endpoint group with a guide page (auth, errors, pagination).
5. Export Postman from the same spec in CI — see Diagrams & downloads.

Next: Custom components.