test(common): add nested dto and swagger examples

Author: evgeniy.chernomortsev

integration/standard-schema/e2e/standard-schema.spec.ts

@@ -118,6 +118,64 @@ describe('StandardSchemaValidationPipe with Zod (e2e)', () => {
         })
         .expect(400);
     });
+
+    it('should create user with valid nested address', () => {
+      return request(server)
+        .post('/users')
+        .send({
+          name: 'John Doe',
+          email: '[email protected]',
+          address: {
+            street: '123 Main St',
+            city: 'New York',
+            zipCode: '10001',
+            country: 'US',
+          },
+        })
+        .expect(201)
+        .expect(res => {
+          expect(res.body.success).to.equal(true);
+          expect(res.body.data.address.street).to.equal('123 Main St');
+          expect(res.body.data.address.city).to.equal('New York');
+          expect(res.body.data.address.zipCode).to.equal('10001');
+          expect(res.body.data.address.country).to.equal('US');
+        });
+    });
+
+    it('should reject invalid nested address zipCode', () => {
+      return request(server)
+        .post('/users')
+        .send({
+          name: 'John Doe',
+          email: '[email protected]',
+          address: {
+            street: '123 Main St',
+            city: 'New York',
+            zipCode: 'invalid',
+            country: 'US',
+          },
+        })
+        .expect(400)
+        .expect(res => {
+          expect(res.body.message).to.be.an('array');
+          expect(res.body.message.some((m: string) => m.includes('zip'))).to.be
+            .true;
+        });
+    });
+
+    it('should reject incomplete nested address', () => {
+      return request(server)
+        .post('/users')
+        .send({
+          name: 'John Doe',
+          email: '[email protected]',
+          address: {
+            street: '123 Main St',
+            // missing city, zipCode, country
+          },
+        })
+        .expect(400);
+    });
   });
 
   describe('POST /users/query', () => {

integration/standard-schema/src/dto.ts

@@ -1,39 +1,114 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { z } from 'zod';
 
 /**
- * Zod schema for CreateUserDto
+ * Zod schema for AddressDto (nested)
  */
-const createUserSchema = z.object({
+export const addressSchema = z.object({
+  street: z.string().min(1, 'Street is required'),
+  city: z.string().min(1, 'City is required'),
+  zipCode: z.string().regex(/^\d{5}(-\d{4})?$/, 'Invalid zip code format'),
+  country: z.string().min(2).max(2, 'Country must be ISO 3166-1 alpha-2 code'),
+});
+
+/**
+ * Nested DTO for address with Swagger documentation.
+ * Uses `implements z.infer<typeof schema>` to ensure type safety.
+ */
+export class AddressDto implements z.infer<typeof addressSchema> {
+  static schema = addressSchema;
+
+  @ApiProperty({ description: 'Street address', example: '123 Main St' })
+  declare street: string;
+
+  @ApiProperty({ description: 'City name', example: 'New York' })
+  declare city: string;
+
+  @ApiProperty({ description: 'ZIP code (US format)', example: '10001' })
+  declare zipCode: string;
+
+  @ApiProperty({
+    description: 'Country code (ISO 3166-1 alpha-2)',
+    example: 'US',
+    minLength: 2,
+    maxLength: 2,
+  })
+  declare country: string;
+}
+
+/**
+ * Zod schema for CreateUserDto with nested address
+ */
+export const createUserSchema = z.object({
   name: z.string().min(2, 'Name must be at least 2 characters'),
   email: z.string().email('Invalid email format'),
   age: z.number().int().min(0).max(150).optional(),
+  address: addressSchema.optional(),
 });
 
 /**
- * DTO with Zod schema for user creation
+ * DTO with Zod schema and Swagger decorators.
+ * Uses `implements z.infer<typeof schema>` to ensure type safety
+ * between the Zod schema and class properties.
  */
-export class CreateUserDto {
+export class CreateUserDto implements z.infer<typeof createUserSchema> {
   static schema = createUserSchema;
 
-  name: string;
-  email: string;
-  age?: number;
+  @ApiProperty({
+    description: 'User name',
+    example: 'John Doe',
+    minLength: 2,
+  })
+  declare name: string;
+
+  @ApiProperty({
+    description: 'User email address',
+    example: '[email protected]',
+    format: 'email',
+  })
+  declare email: string;
+
+  @ApiPropertyOptional({
+    description: 'User age',
+    example: 30,
+    minimum: 0,
+    maximum: 150,
+  })
+  declare age?: number;
+
+  @ApiPropertyOptional({
+    description: 'User address',
+    type: () => AddressDto,
+  })
+  declare address?: AddressDto;
 }
 
 /**
  * Zod schema for QueryDto
  */
-const querySchema = z.object({
+export const querySchema = z.object({
   limit: z.coerce.number().int().min(1).max(100).optional(),
   offset: z.coerce.number().int().min(0).optional(),
 });
 
 /**
  * DTO with Zod schema for query parameters
  */
-export class QueryDto {
+export class QueryDto implements z.infer<typeof querySchema> {
   static schema = querySchema;
 
-  limit?: number;
-  offset?: number;
+  @ApiPropertyOptional({
+    description: 'Number of items to return',
+    example: 10,
+    minimum: 1,
+    maximum: 100,
+  })
+  declare limit?: number;
+
+  @ApiPropertyOptional({
+    description: 'Number of items to skip',
+    example: 0,
+    minimum: 0,
+  })
+  declare offset?: number;
 }

package-lock.json

@@ -98,6 +98,7 @@
     "@nestjs/apollo": "13.2.3",
     "@nestjs/graphql": "13.2.3",
     "@nestjs/mongoose": "11.0.4",
+    "@nestjs/swagger": "11.2.3",
     "@nestjs/typeorm": "11.0.0",
     "@types/amqplib": "0.10.8",
     "@types/bytes": "3.1.5",