Context
API validation uses ad-hoc Zod schemas scattered across route handlers. There is no single source of truth for API contracts.
Current Limitation/Problem
Request validation is inconsistent. Some routes validate, others do not. There is no generated OpenAPI spec, making client generation and documentation difficult.
Expected Outcome
All API endpoints use OpenAPI 3.1 schemas as the single source of truth, with automatic request validation, response serialization, and documentation generation.
Acceptance Criteria
- Define OpenAPI schemas for all request/response types
- Generate Zod validation schemas from OpenAPI definitions
- Auto-validate all incoming requests against OpenAPI spec
- Auto-serialize and validate responses
- Generate OpenAPI spec document from route definitions
- Expose Swagger UI at
/api-docs
- Catch schema violations in tests via OpenAPI conformance check
- Support for oneOf, anyOf, allOf composition patterns
- Deprecation annotations in OpenAPI with sunset headers
Technical Scope
packages/api-spec/ - OpenAPI definitions package- Code generation from OpenAPI to Zod
backend/src/middleware/openapi-validator.ts - validation middleware- swagger-ui-express or Scalar for docs UI
- Test utility:
validateResponseAgainstOpenAPI
- Edge cases: file uploads, binary responses, streaming endpoints
Context
API validation uses ad-hoc Zod schemas scattered across route handlers. There is no single source of truth for API contracts.
Current Limitation/Problem
Request validation is inconsistent. Some routes validate, others do not. There is no generated OpenAPI spec, making client generation and documentation difficult.
Expected Outcome
All API endpoints use OpenAPI 3.1 schemas as the single source of truth, with automatic request validation, response serialization, and documentation generation.
Acceptance Criteria
/api-docsTechnical Scope
packages/api-spec/- OpenAPI definitions packagebackend/src/middleware/openapi-validator.ts- validation middlewarevalidateResponseAgainstOpenAPI