Skip to content

LMS OpenAPI generation

Problem

CMS publishes an OpenAPI document for its API via apps/cms/src/lib/api/openapi/generate.ts. LMS has a small API surface (webhooks, impersonation, asset proxies, NextAuth) but no equivalent contract, so external integrators have to read the source.

This ticket is low priority but cheap once T-003 (error contract) lands, because the shared error/code enum makes response schemas trivial to express.

Proposal

  1. Add apps/lms/src/lib/api/openapi/generate.ts modeled on the CMS version.
  2. Register Zod schemas (auth payloads, revalidate payload, error responses) with the OpenAPI registry already used in apps/lms/src/schemas/.
  3. Add an npm script openapi:generate that writes apps/lms/public/openapi.json.
  4. Wire into predev / CI build so the file is regenerated when schemas change.
  5. Document the endpoint in apps/lms/docs/.

Acceptance criteria

  • npm run openapi:generate --workspace apps/lms produces a valid OpenAPI 3.x document at apps/lms/public/openapi.yaml.
  • Document includes every LMS route handler under apps/lms/src/app/api/** (excluding deliberate exclusions).
  • Generation is guarded in CI via openapi-sync.test.ts (runs under turbo run test:coverage, same pattern as CMS).
  • npm run check passes.

Out of scope

  • Adding OpenAPI for server actions (actions are internal transport per standing decision).

Notes / decisions log

  • 2026-05-24: Ticket created from monorepo audit.
  • 2026-05-25: Implemented on existing scaffolding (scripts/openapi-generate.ts, src/schemas/openapi-registry.ts, /admin/api-docs Swagger UI). Output format is public/openapi.yaml (not JSON; matches CMS and Swagger UI). CI guard follows CMS: tests/unit/openapi-sync.test.ts compares committed YAML to buildOpenApiYaml() — no change to npm run check or .github/workflows/ci.yml. Added openapi-coverage.test.ts for route registration drift. Documented exclusions: /api/auth/*, /api/test/*. Error envelope uses ApiErrorEnvelope (error, code, issues?) per T-003. Reference doc: apps/lms/docs/reference/openapi.md.