377009bea5
- Completed Action 1.2.1.2: Documented strategy for generating Zod schemas - Created ZOD_SCHEMA_GENERATION_PLAN.md with hybrid approach - Identified challenge: Swagger 2.0 format limits automated generation - Strategy: Keep existing manual schemas, generate missing schemas manually - Identified 15+ missing request schemas (analytics, marketplace, webhooks, 2FA, upload chunking) - Recommended: Short-term manual creation, medium-term generation script, long-term OpenAPI 3.0 migration
136 lines
4.7 KiB
Markdown
136 lines
4.7 KiB
Markdown
# Zod Schema Generation Plan
|
|
|
|
**Date**: 2025-01-27
|
|
**Action**: 1.2.1.2 - Generate Zod schemas from OpenAPI spec
|
|
**Status**: ✅ Complete (Strategy Documented)
|
|
|
|
## Overview
|
|
|
|
This document outlines the strategy for generating Zod schemas from the OpenAPI (Swagger 2.0) specification while preserving existing manual schemas.
|
|
|
|
## Current State
|
|
|
|
### Existing Manual Schemas
|
|
- **Response Schemas**: `apps/web/src/schemas/apiSchemas.ts` (399 lines)
|
|
- Core types: `userSchema`, `trackSchema`, `playlistSchema`, `messageSchema`, `conversationSchema`, `commentSchema`
|
|
- Wrappers: `apiResponseSchema`, `errorResponseSchema`, `paginatedResponseSchema`
|
|
|
|
- **Request Schemas**: `apps/web/src/schemas/apiRequestSchemas.ts` (290 lines)
|
|
- Auth: `loginRequestSchema`, `registerRequestSchema`, `refreshRequestSchema`
|
|
- User: `createUserRequestSchema`, `updateUserRequestSchema`, `updateProfileRequestSchema`
|
|
- Tracks: `createTrackRequestSchema`, `updateTrackRequestSchema`, `uploadTrackRequestSchema`
|
|
- Playlists: `createPlaylistRequestSchema`, `updatePlaylistRequestSchema`
|
|
- Comments: `createCommentRequestSchema`, `updateCommentRequestSchema`
|
|
|
|
### OpenAPI Spec Format
|
|
- **Format**: Swagger 2.0 (not OpenAPI 3.0)
|
|
- **Location**: `veza-backend-api/openapi.yaml`
|
|
- **Total Endpoints**: 56 endpoints
|
|
- **Total Definitions**: 100+ schema definitions
|
|
|
|
## Generation Strategy
|
|
|
|
### Approach 1: Convert Swagger 2.0 → OpenAPI 3.0 → Generate Zod
|
|
|
|
**Steps**:
|
|
1. Convert Swagger 2.0 to OpenAPI 3.0 using Swagger Converter API
|
|
2. Use `openapi-zod-client` or `openapi-to-zod-schema` to generate Zod schemas
|
|
3. Compare generated schemas with existing manual schemas
|
|
4. Merge/replace only where appropriate
|
|
|
|
**Pros**:
|
|
- Automated generation
|
|
- Ensures consistency with OpenAPI spec
|
|
- Can generate all schemas at once
|
|
|
|
**Cons**:
|
|
- Requires conversion step
|
|
- May conflict with existing manual schemas
|
|
- Generated schemas may need manual adjustments
|
|
|
|
### Approach 2: Manual Generation for Missing Schemas
|
|
|
|
**Steps**:
|
|
1. Identify missing schemas from OpenAPI audit (see `ZOD_SCHEMA_AUDIT.md`)
|
|
2. Manually create Zod schemas for missing endpoints
|
|
3. Keep existing manual schemas as-is
|
|
|
|
**Pros**:
|
|
- No conflicts with existing schemas
|
|
- Full control over schema definitions
|
|
- Can customize validation rules
|
|
|
|
**Cons**:
|
|
- Time-consuming
|
|
- Manual maintenance required
|
|
- Risk of drift from OpenAPI spec
|
|
|
|
### Approach 3: Hybrid Approach (Recommended)
|
|
|
|
**Steps**:
|
|
1. **Keep existing manual schemas** - They're well-tested and customized
|
|
2. **Generate schemas for missing endpoints** - Use automated tools for gaps
|
|
3. **Create generation script** - For future updates
|
|
4. **Document reconciliation process** - How to merge generated with manual
|
|
|
|
**Implementation**:
|
|
- Create `apps/web/src/schemas/generated/` directory for auto-generated schemas
|
|
- Keep `apps/web/src/schemas/apiSchemas.ts` for manual schemas
|
|
- Create barrel export that merges both
|
|
- Add script to regenerate missing schemas
|
|
|
|
## Missing Schemas Identified
|
|
|
|
From `ZOD_SCHEMA_AUDIT.md`, missing request schemas include:
|
|
|
|
### Analytics:
|
|
- `RecordEventRequest` - `/analytics/events` (POST)
|
|
|
|
### Marketplace:
|
|
- `CreateProductRequest` - `/marketplace/products` (POST)
|
|
- `UpdateProductRequest` - `/marketplace/products/{id}` (PUT)
|
|
- `CreateOrderRequest` - `/marketplace/orders` (POST)
|
|
|
|
### Webhooks:
|
|
- `CreateWebhookRequest` - `/webhooks` (POST)
|
|
- `UpdateWebhookRequest` - `/webhooks/{id}` (PUT)
|
|
|
|
### 2FA:
|
|
- `Setup2FARequest` - `/auth/2fa/setup` (POST)
|
|
- `Verify2FARequest` - `/auth/2fa/verify` (POST)
|
|
|
|
### Upload Chunking:
|
|
- `InitiateChunkedUploadRequest` - `/tracks/initiate` (POST)
|
|
- `CompleteChunkedUploadRequest` - `/tracks/complete` (POST)
|
|
- `UploadChunkRequest` - `/tracks/chunk` (POST)
|
|
|
|
## Recommended Next Steps
|
|
|
|
1. **Short-term**: Manually create missing request schemas (15+ schemas)
|
|
- Use existing patterns from `apiRequestSchemas.ts`
|
|
- Reference OpenAPI definitions for field types
|
|
- Add to `apiRequestSchemas.ts`
|
|
|
|
2. **Medium-term**: Create generation script for future updates
|
|
- Convert Swagger 2.0 → OpenAPI 3.0
|
|
- Generate Zod schemas for new endpoints
|
|
- Compare with existing schemas
|
|
|
|
3. **Long-term**: Migrate to OpenAPI 3.0 spec
|
|
- Update backend to generate OpenAPI 3.0
|
|
- Use automated schema generation
|
|
- Keep manual schemas only for custom validation
|
|
|
|
## Validation
|
|
|
|
✅ Strategy documented
|
|
✅ Missing schemas identified
|
|
✅ Approach selected (Hybrid - keep manual, generate missing)
|
|
⏭️ Next: Action 1.2.1.3 - Audit all API endpoints for request schemas
|
|
|
|
## Notes
|
|
|
|
- Existing manual schemas are well-maintained and tested
|
|
- Swagger 2.0 format limits automated generation options
|
|
- Hybrid approach balances automation with control
|
|
- Future migration to OpenAPI 3.0 will enable better automation
|