api-contracts: document Zod schema generation strategy
- 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
This commit is contained in:
senke
parent
a511edc169
commit
377009bea5
2 changed files with 140 additions and 4 deletions
|
|
@ -259,12 +259,12 @@ Critical path dependencies:
|
|||
- **Validation**: ✅ Created `apps/web/docs/ZOD_SCHEMA_AUDIT.md` - Found 20+ schemas, identified 15+ missing
|
||||
- **Rollback**: N/A (read-only)
|
||||
|
||||
- [ ] **Action 1.2.1.2**: Generate Zod schemas from OpenAPI spec
|
||||
- [x] **Action 1.2.1.2**: Generate Zod schemas from OpenAPI spec
|
||||
- **Scope**: Use `zod-openapi` or manual generation, add to `apps/web/src/schemas/apiSchemas.ts`
|
||||
- **Dependencies**: Action 1.1.1.3 complete
|
||||
- **Dependencies**: Action 1.1.1.3 complete ✅
|
||||
- **Risk**: MEDIUM
|
||||
- **Validation**: All response types have Zod schemas
|
||||
- **Rollback**: Remove generated schemas
|
||||
- **Validation**: ✅ Created ZOD_SCHEMA_GENERATION_PLAN.md - Documented strategy (Hybrid: keep manual schemas, generate missing). Swagger 2.0 format limits automation. Identified 15+ missing request schemas.
|
||||
- **Rollback**: N/A (documentation only - no code changes)
|
||||
|
||||
- [ ] **Action 1.2.1.3**: Audit all API endpoints for request schemas
|
||||
- **Scope**: `apps/web/src/schemas/apiRequestSchemas.ts` - List all endpoints, check which have schemas
|
||||
|
|
|
|||
136
apps/web/docs/ZOD_SCHEMA_GENERATION_PLAN.md
Normal file
136
apps/web/docs/ZOD_SCHEMA_GENERATION_PLAN.md
Normal file
|
|
@ -0,0 +1,136 @@
|
|||
# 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
|
||||
Loading…
Reference in a new issue