Transforms OpenAPI specs into browsable MDX pages with interactive components.
The OpenAPI sync (sync/openapi.ts) is a sub-pipeline bolted onto the main sync engine. It collects specs from the config, dereferences $refs, generates one MDX page per operation, and builds sidebar items grouped by tag.
| # | Step | What it does |
|---|---|---|
| 1 | Collect configs | Gather OpenAPI configs from root config.openapi and entry-level openapi fields (apps, packages, and workspace items) |
| 2 | Check mtime | Stat the spec file and compare its mtime to the previous manifest to decide whether a shared cached dereference can be reused |
| 3 | Dereference | Resolve all $refs via @apidevtools/swagger-parser (or use cached result) |
| 4 | Extract operations | Pull operations from paths, group by tag |
| 5 | Generate MDX | One .mdx per operation (renders <OpenAPIOperation>) + overview page (<OpenAPIOverview>) |
| 6 | Build sidebar | Sidebar items grouped by tag with configurable layout (method-path or title) |
| 7 | Emit spec | Emit dereferenced spec as a virtual openapi.json page (written by the sync engine's copy step) |
In dev mode, a shared Map<string, unknown> is created once and threaded through all sync passes. See Dev Mode — OpenAPI Cache for lifecycle details.