feat: document more endpoints

packages/server/src/modules/WarehousesTransfers/WarehouseTransfers.controller.ts

@@ -9,16 +9,25 @@ import {
   Query,
   Inject,
 } from '@nestjs/common';
-import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+import {
+  ApiExtraModels,
+  ApiOperation,
+  ApiResponse,
+  ApiTags,
+  getSchemaPath,
+} from '@nestjs/swagger';
 import { WarehouseTransferApplication } from './WarehouseTransferApplication';
 import {
   CreateWarehouseTransferDto,
   EditWarehouseTransferDto,
 } from './dtos/WarehouseTransfer.dto';
 import { GetWarehouseTransfersQueryDto } from '../Warehouses/dtos/GetWarehouseTransfersQuery.dto';
+import { WarehouseTransferResponseDto } from './dtos/WarehouseTransferResponse.dto';
+import { PaginatedResponseDto } from '@/common/dtos/PaginatedResults.dto';
 
 @Controller('warehouse-transfers')
 @ApiTags('Warehouse Transfers')
+@ApiExtraModels(WarehouseTransferResponseDto, PaginatedResponseDto)
 export class WarehouseTransfersController {
   /**
    * @param {WarehouseTransferApplication} warehouseTransferApplication - Warehouse transfer application.
@@ -129,6 +138,19 @@ export class WarehouseTransfersController {
     status: 200,
     description:
       'The warehouse transfer transactions have been retrieved successfully.',
+    schema: {
+      allOf: [
+        { $ref: getSchemaPath(PaginatedResponseDto) },
+        {
+          properties: {
+            data: {
+              type: 'array',
+              items: { $ref: getSchemaPath(WarehouseTransferResponseDto) },
+            },
+          },
+        },
+      ],
+    },
   })
   async getWarehousesTransfers(@Query() query: GetWarehouseTransfersQueryDto) {
     const { warehousesTransfers, pagination, filter } =
@@ -150,6 +172,9 @@ export class WarehouseTransfersController {
     status: 200,
     description:
       'The warehouse transfer transaction details have been retrieved successfully.',
+    schema: {
+      $ref: getSchemaPath(WarehouseTransferResponseDto),
+    },
   })
   async getWarehouseTransfer(@Param('id') id: number) {
     const warehouseTransfer =

packages/server/src/modules/WarehousesTransfers/dtos/WarehouseTransferResponse.dto.ts

@@ -0,0 +1,151 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+
+export class WarehouseTransferEntryResponseDto {
+  @ApiProperty({
+    description: 'The ID of the warehouse transfer entry',
+    example: 1,
+  })
+  id: number;
+
+  @ApiProperty({
+    description: 'The ID of the item being transferred',
+    example: 1,
+  })
+  itemId: number;
+
+  @ApiProperty({
+    description: 'The quantity of items being transferred',
+    example: 100,
+  })
+  quantity: number;
+
+  @ApiProperty({
+    description: 'The cost per unit of the item',
+    example: 10.5,
+  })
+  cost: number;
+
+  @ApiProperty({
+    description: 'The total cost of the transfer entry',
+    example: 1050.0,
+  })
+  total: number;
+
+  @ApiProperty({
+    description: 'The formatted quantity of items being transferred',
+    example: '100.00',
+  })
+  formattedQuantity: string;
+
+  @ApiProperty({
+    description: 'The formatted cost per unit of the item',
+    example: '$10.50',
+  })
+  formattedCost: string;
+
+  @ApiProperty({
+    description: 'The formatted total cost of the transfer entry',
+    example: '$1,050.00',
+  })
+  formattedTotal: string;
+
+  @ApiProperty({
+    description: 'The item details',
+    type: 'object',
+  })
+  item: any;
+}
+
+export class WarehouseTransferResponseDto {
+  @ApiProperty({
+    description: 'The ID of the warehouse transfer',
+    example: 1,
+  })
+  id: number;
+
+  @ApiProperty({
+    description: 'The date of the warehouse transfer',
+    example: '2024-03-20',
+  })
+  date: Date;
+
+  @ApiProperty({
+    description: 'The formatted date of the warehouse transfer',
+    example: 'Mar 20, 2024',
+  })
+  formattedDate: string;
+
+  @ApiProperty({
+    description: 'The transaction number of the warehouse transfer',
+    example: 'WT-2024-001',
+  })
+  transactionNumber: string;
+
+  @ApiProperty({
+    description: 'The ID of the source warehouse',
+    example: 1,
+  })
+  fromWarehouseId: number;
+
+  @ApiProperty({
+    description: 'The ID of the destination warehouse',
+    example: 2,
+  })
+  toWarehouseId: number;
+
+  @ApiProperty({
+    description: 'The date when the transfer was initiated',
+    example: '2024-03-20T10:00:00Z',
+  })
+  transferInitiatedAt: Date;
+
+  @ApiProperty({
+    description: 'The date when the transfer was delivered',
+    example: '2024-03-21T15:00:00Z',
+  })
+  transferDeliveredAt: Date;
+
+  @ApiProperty({
+    description: 'Whether the transfer has been initiated',
+    example: true,
+  })
+  isInitiated: boolean;
+
+  @ApiProperty({
+    description: 'Whether the transfer has been completed',
+    example: true,
+  })
+  isTransferred: boolean;
+
+  @ApiProperty({
+    description: 'The source warehouse details',
+    type: 'object',
+  })
+  fromWarehouse: any;
+
+  @ApiProperty({
+    description: 'The destination warehouse details',
+    type: 'object',
+  })
+  toWarehouse: any;
+
+  @ApiProperty({
+    description: 'The entries of the warehouse transfer',
+    type: [WarehouseTransferEntryResponseDto],
+  })
+  @Type(() => WarehouseTransferEntryResponseDto)
+  entries: WarehouseTransferEntryResponseDto[];
+
+  @ApiProperty({
+    description: 'The creation date of the warehouse transfer',
+    example: '2024-03-20T09:00:00Z',
+  })
+  createdAt: Date;
+
+  @ApiProperty({
+    description: 'The last update date of the warehouse transfer',
+    example: '2024-03-21T15:00:00Z',
+  })
+  updatedAt: Date;
+}