feat: add swagger docs for responses

packages/server/src/modules/Customers/Customers.controller.ts

@@ -13,35 +13,66 @@ import {
   ICustomerOpeningBalanceEditDTO,
   ICustomersFilter,
 } from './types/Customers.types';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+  ApiOperation,
+  ApiResponse,
+  ApiTags,
+  ApiExtraModels,
+  getSchemaPath,
+} from '@nestjs/swagger';
 import { CreateCustomerDto } from './dtos/CreateCustomer.dto';
 import { EditCustomerDto } from './dtos/EditCustomer.dto';
+import { CustomerResponseDto } from './dtos/CustomerResponse.dto';
 
 @Controller('customers')
 @ApiTags('Customers')
+@ApiExtraModels(CustomerResponseDto)
 export class CustomersController {
   constructor(private customersApplication: CustomersApplication) {}
 
   @Get(':id')
   @ApiOperation({ summary: 'Retrieves the customer details.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The customer details have been successfully retrieved.',
+    schema: { $ref: getSchemaPath(CustomerResponseDto) },
+  })
   getCustomer(@Param('id') customerId: number) {
     return this.customersApplication.getCustomer(customerId);
   }
 
   @Get()
   @ApiOperation({ summary: 'Retrieves the customers paginated list.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The customers have been successfully retrieved.',
+    schema: {
+      type: 'array',
+      items: { $ref: getSchemaPath(CustomerResponseDto) },
+    },
+  })
   getCustomers(@Query() filterDTO: Partial<ICustomersFilter>) {
     return this.customersApplication.getCustomers(filterDTO);
   }
 
   @Post()
   @ApiOperation({ summary: 'Create a new customer.' })
+  @ApiResponse({
+    status: 201,
+    description: 'The customer has been successfully created.',
+    schema: { $ref: getSchemaPath(CustomerResponseDto) },
+  })
   createCustomer(@Body() customerDTO: CreateCustomerDto) {
     return this.customersApplication.createCustomer(customerDTO);
   }
 
   @Put(':id')
   @ApiOperation({ summary: 'Edit the given customer.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The customer has been successfully updated.',
+    schema: { $ref: getSchemaPath(CustomerResponseDto) },
+  })
   editCustomer(
     @Param('id') customerId: number,
     @Body() customerDTO: EditCustomerDto,
@@ -51,12 +82,21 @@ export class CustomersController {
 
   @Delete(':id')
   @ApiOperation({ summary: 'Delete the given customer.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The customer has been successfully deleted.',
+  })
   deleteCustomer(@Param('id') customerId: number) {
     return this.customersApplication.deleteCustomer(customerId);
   }
 
   @Put(':id/opening-balance')
   @ApiOperation({ summary: 'Edit the opening balance of the given customer.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The customer opening balance has been successfully updated.',
+    schema: { $ref: getSchemaPath(CustomerResponseDto) },
+  })
   editOpeningBalance(
     @Param('id') customerId: number,
     @Body() openingBalanceDTO: ICustomerOpeningBalanceEditDTO,

packages/server/src/modules/Customers/Customers.module.ts

@@ -36,7 +36,7 @@ import { DynamicListModule } from '../DynamicListing/DynamicList.module';
     GetCustomerService,
     CustomersExportable,
     CustomersImportable,
-    GetCustomers
+    GetCustomers,
   ],
 })
 export class CustomersModule {}

packages/server/src/modules/Customers/dtos/CreateCustomer.dto.ts

@@ -10,22 +10,38 @@ import { ApiProperty } from '@nestjs/swagger';
 import { ContactAddressDto } from './ContactAddress.dto';
 
 export class CreateCustomerDto extends ContactAddressDto {
-  @ApiProperty({ required: true, description: 'Customer type' })
+  @ApiProperty({
+    required: true,
+    description: 'Customer type',
+    example: 'business',
+  })
   @IsString()
   @IsNotEmpty()
   customerType: string;
 
-  @ApiProperty({ required: true, description: 'Currency code' })
+  @ApiProperty({
+    required: true,
+    description: 'Currency code',
+    example: 'USD',
+  })
   @IsString()
   @IsNotEmpty()
   currencyCode: string;
 
-  @ApiProperty({ required: false, description: 'Opening balance' })
+  @ApiProperty({
+    required: false,
+    description: 'Opening balance',
+    example: 5000.0,
+  })
   @IsOptional()
   @IsNumber()
   openingBalance?: number;
 
-  @ApiProperty({ required: false, description: 'Opening balance date' })
+  @ApiProperty({
+    required: false,
+    description: 'Opening balance date',
+    example: '2024-01-01',
+  })
   @IsOptional()
   @IsString()
   openingBalanceAt?: string;
@@ -33,52 +49,89 @@ export class CreateCustomerDto extends ContactAddressDto {
   @ApiProperty({
     required: false,
     description: 'Opening balance exchange rate',
+    example: 1.0,
   })
   @IsOptional()
   @IsNumber()
   openingBalanceExchangeRate?: number;
 
-  @ApiProperty({ required: false, description: 'Opening balance branch ID' })
+  @ApiProperty({
+    required: false,
+    description: 'Opening balance branch ID',
+    example: 101,
+  })
   @IsOptional()
   @IsNumber()
   openingBalanceBranchId?: number;
 
-  @ApiProperty({ required: false, description: 'Salutation' })
+  @ApiProperty({
+    required: false,
+    description: 'Salutation',
+    example: 'Mr.',
+  })
   @IsOptional()
   @IsString()
   salutation?: string;
 
-  @ApiProperty({ required: false, description: 'First name' })
+  @ApiProperty({
+    required: false,
+    description: 'First name',
+    example: 'John',
+  })
   @IsOptional()
   @IsString()
   firstName?: string;
 
-  @ApiProperty({ required: false, description: 'Last name' })
+  @ApiProperty({
+    required: false,
+    description: 'Last name',
+    example: 'Smith',
+  })
   @IsOptional()
   @IsString()
   lastName?: string;
 
-  @ApiProperty({ required: false, description: 'Company name' })
+  @ApiProperty({
+    required: false,
+    description: 'Company name',
+    example: 'Acme Corporation',
+  })
   @IsOptional()
   @IsString()
   companyName?: string;
 
-  @ApiProperty({ required: true, description: 'Display name' })
+  @ApiProperty({
+    required: true,
+    description: 'Display name',
+    example: 'Acme Corporation',
+  })
   @IsString()
   @IsNotEmpty()
   displayName: string;
 
-  @ApiProperty({ required: false, description: 'Website' })
+  @ApiProperty({
+    required: false,
+    description: 'Website',
+    example: 'https://www.acmecorp.com',
+  })
   @IsOptional()
   @IsString()
   website?: string;
 
-  @ApiProperty({ required: false, description: 'Email' })
+  @ApiProperty({
+    required: false,
+    description: 'Email',
+    example: 'contact@acmecorp.com',
+  })
   @IsOptional()
   @IsEmail()
   email?: string;
 
-  @ApiProperty({ required: false, description: 'Work phone' })
+  @ApiProperty({
+    required: false,
+    description: 'Work phone',
+    example: '+1 (555) 123-4567',
+  })
   @IsOptional()
   @IsString()
   workPhone?: string;

packages/server/src/modules/Customers/dtos/CustomerResponse.dto.ts

@@ -0,0 +1,118 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+
+export class CustomerResponseDto {
+  @ApiProperty({ example: 1500.0 })
+  balance: number;
+
+  @ApiProperty({ example: 'USD' })
+  currencyCode: string;
+
+  @ApiProperty({ example: 1000.0 })
+  openingBalance: number;
+
+  @ApiProperty({ example: '2024-01-01T00:00:00Z' })
+  @Type(() => Date)
+  openingBalanceAt: Date;
+
+  @ApiProperty({ example: 1.0 })
+  openingBalanceExchangeRate: number;
+
+  @ApiProperty({ required: false, example: 1 })
+  openingBalanceBranchId?: number;
+
+  @ApiProperty({ required: false, example: 'Mr.' })
+  salutation?: string;
+
+  @ApiProperty({ required: false, example: 'John' })
+  firstName?: string;
+
+  @ApiProperty({ required: false, example: 'Doe' })
+  lastName?: string;
+
+  @ApiProperty({ required: false, example: 'Acme Corporation' })
+  companyName?: string;
+
+  @ApiProperty({ example: 'John Doe - Acme Corporation' })
+  displayName: string;
+
+  @ApiProperty({ required: false, example: 'john.doe@acme.com' })
+  email?: string;
+
+  @ApiProperty({ required: false, example: '+1 (555) 123-4567' })
+  workPhone?: string;
+
+  @ApiProperty({ required: false, example: '+1 (555) 987-6543' })
+  personalPhone?: string;
+
+  @ApiProperty({ required: false, example: 'https://www.acme.com' })
+  website?: string;
+
+  @ApiProperty({ required: false, example: '123 Business Ave' })
+  billingAddress1?: string;
+
+  @ApiProperty({ required: false, example: 'Suite 100' })
+  billingAddress2?: string;
+
+  @ApiProperty({ required: false, example: 'New York' })
+  billingAddressCity?: string;
+
+  @ApiProperty({ required: false, example: 'United States' })
+  billingAddressCountry?: string;
+
+  @ApiProperty({ required: false, example: 'billing@acme.com' })
+  billingAddressEmail?: string;
+
+  @ApiProperty({ required: false, example: '10001' })
+  billingAddressPostcode?: string;
+
+  @ApiProperty({ required: false, example: '+1 (555) 111-2222' })
+  billingAddressPhone?: string;
+
+  @ApiProperty({ required: false, example: 'NY' })
+  billingAddressState?: string;
+
+  @ApiProperty({ required: false, example: '456 Shipping St' })
+  shippingAddress1?: string;
+
+  @ApiProperty({ required: false, example: 'Unit 200' })
+  shippingAddress2?: string;
+
+  @ApiProperty({ required: false, example: 'Los Angeles' })
+  shippingAddressCity?: string;
+
+  @ApiProperty({ required: false, example: 'United States' })
+  shippingAddressCountry?: string;
+
+  @ApiProperty({ required: false, example: 'shipping@acme.com' })
+  shippingAddressEmail?: string;
+
+  @ApiProperty({ required: false, example: '90001' })
+  shippingAddressPostcode?: string;
+
+  @ApiProperty({ required: false, example: '+1 (555) 333-4444' })
+  shippingAddressPhone?: string;
+
+  @ApiProperty({ required: false, example: 'CA' })
+  shippingAddressState?: string;
+
+  @ApiProperty({ example: 'Important client with regular monthly orders' })
+  note: string;
+
+  @ApiProperty({ example: true })
+  active: boolean;
+
+  @ApiProperty({ example: '2024-01-01T00:00:00Z' })
+  @Type(() => Date)
+  createdAt: Date;
+
+  @ApiProperty({ example: '2024-01-01T00:00:00Z' })
+  @Type(() => Date)
+  updatedAt: Date;
+
+  @ApiProperty({ example: 1000.0 })
+  localOpeningBalance: number;
+
+  @ApiProperty({ example: 1500.0 })
+  closingBalance: number;
+}