feat: update endpoint swagger docs

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

@@ -1,4 +1,11 @@
-import { ApiOperation, ApiParam, ApiTags } from '@nestjs/swagger';
+import {
+  ApiExtraModels,
+  ApiOperation,
+  ApiParam,
+  ApiResponse,
+  ApiTags,
+  getSchemaPath,
+} from '@nestjs/swagger';
 import {
   Controller,
   Post,
@@ -12,9 +19,13 @@ import {
 import { BillsApplication } from './Bills.application';
 import { IBillsFilter } from './Bills.types';
 import { CreateBillDto, EditBillDto } from './dtos/Bill.dto';
+import { BillResponseDto } from './dtos/BillResponse.dto';
+import { PaginatedResponseDto } from '@/common/dtos/PaginatedResults.dto';
 
 @Controller('bills')
 @ApiTags('Bills')
+@ApiExtraModels(BillResponseDto)
+@ApiExtraModels(PaginatedResponseDto)
 export class BillsController {
   constructor(private billsApplication: BillsApplication) {}
 
@@ -50,6 +61,23 @@ export class BillsController {
 
   @Get()
   @ApiOperation({ summary: 'Retrieves the bills.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The bill details has been retrieved successfully',
+    schema: {
+      allOf: [
+        { $ref: getSchemaPath(PaginatedResponseDto) },
+        {
+          properties: {
+            data: {
+              type: 'array',
+              items: { $ref: getSchemaPath(BillResponseDto) },
+            },
+          },
+        },
+      ],
+    },
+  })
   @ApiParam({
     name: 'id',
     required: true,
@@ -61,7 +89,9 @@ export class BillsController {
   }
 
   @Get(':id/payment-transactions')
-  @ApiOperation({ summary: 'Retrieve the specific bill associated payment transactions.' })
+  @ApiOperation({
+    summary: 'Retrieve the specific bill associated payment transactions.',
+  })
   @ApiParam({
     name: 'id',
     required: true,
@@ -74,6 +104,13 @@ export class BillsController {
 
   @Get(':id')
   @ApiOperation({ summary: 'Retrieves the bill details.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The bill details have been successfully retrieved.',
+    schema: {
+      $ref: getSchemaPath(BillResponseDto),
+    },
+  })
   @ApiParam({
     name: 'id',
     required: true,

packages/server/src/modules/Bills/dtos/BillResponse.dto.ts

@@ -0,0 +1,202 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { ItemEntryDto } from '@/modules/TransactionItemEntry/dto/ItemEntry.dto';
+import { AttachmentLinkDto } from '@/modules/Attachments/dtos/Attachment.dto';
+import { DiscountType } from '@/common/types/Discount';
+
+export class BillResponseDto {
+  @ApiProperty({
+    description: 'The unique identifier of the bill',
+    example: 1,
+  })
+  id: number;
+
+  @ApiProperty({
+    description: 'The bill number',
+    example: 'BILL-2024-001',
+  })
+  billNumber: string;
+
+  @ApiProperty({
+    description: 'The date the bill was issued',
+    example: '2024-03-15T00:00:00Z',
+  })
+  billDate: Date;
+
+  @ApiProperty({
+    description: 'The due date of the bill',
+    example: '2024-04-15T00:00:00Z',
+  })
+  dueDate: Date;
+
+  @ApiProperty({
+    description: 'The reference number',
+    example: 'PO-2024-001',
+    required: false,
+  })
+  referenceNo?: string;
+
+  @ApiProperty({
+    description: 'The ID of the vendor',
+    example: 1001,
+  })
+  vendorId: number;
+
+  @ApiProperty({
+    description: 'The exchange rate for currency conversion',
+    example: 1.25,
+    required: false,
+  })
+  exchangeRate?: number;
+
+  @ApiProperty({
+    description: 'The currency code',
+    example: 'USD',
+    required: false,
+  })
+  currencyCode?: string;
+
+  @ApiProperty({
+    description: 'Additional notes about the bill',
+    example: 'Office supplies and equipment for Q2 2024',
+    required: false,
+  })
+  note?: string;
+
+  @ApiProperty({
+    description: 'Whether tax is inclusive in the item rates',
+    example: false,
+    required: false,
+  })
+  isInclusiveTax?: boolean;
+
+  @ApiProperty({
+    description: 'The line items of the bill',
+    type: [ItemEntryDto],
+  })
+  entries: ItemEntryDto[];
+
+  @ApiProperty({
+    description: 'The ID of the warehouse',
+    example: 101,
+    required: false,
+  })
+  warehouseId?: number;
+
+  @ApiProperty({
+    description: 'The ID of the branch',
+    example: 201,
+    required: false,
+  })
+  branchId?: number;
+
+  @ApiProperty({
+    description: 'The ID of the project',
+    example: 301,
+    required: false,
+  })
+  projectId?: number;
+
+  @ApiProperty({
+    description: 'The attachments of the bill',
+    type: [AttachmentLinkDto],
+    required: false,
+  })
+  attachments?: AttachmentLinkDto[];
+
+  @ApiProperty({
+    description: 'The discount value',
+    example: 100,
+    required: false,
+  })
+  discount?: number;
+
+  @ApiProperty({
+    description: 'The type of discount (percentage or fixed)',
+    enum: DiscountType,
+    example: DiscountType.Amount,
+    required: false,
+  })
+  discountType?: DiscountType;
+
+  @ApiProperty({
+    description: 'The adjustment amount',
+    example: 50,
+    required: false,
+  })
+  adjustment?: number;
+
+  @ApiProperty({
+    description: 'The total amount of tax withheld',
+    example: 50,
+    required: false,
+  })
+  taxAmountWithheld?: number;
+
+  @ApiProperty({
+    description: 'The balance of the bill',
+    example: 1000,
+  })
+  balance: number;
+
+  @ApiProperty({
+    description: 'The amount paid',
+    example: 500,
+  })
+  paymentAmount: number;
+
+  @ApiProperty({
+    description: 'The amount credited',
+    example: 0,
+    required: false,
+  })
+  creditedAmount?: number;
+
+  @ApiProperty({
+    description: 'The subtotal amount before tax and adjustments',
+    example: 900,
+  })
+  subtotal: number;
+
+  @ApiProperty({
+    description: 'The total amount including tax and adjustments',
+    example: 1000,
+  })
+  total: number;
+
+  @ApiProperty({
+    description: 'The due amount remaining to be paid',
+    example: 500,
+  })
+  dueAmount: number;
+
+  @ApiProperty({
+    description: 'Whether the bill is overdue',
+    example: false,
+  })
+  isOverdue: boolean;
+
+  @ApiProperty({
+    description: 'Whether the bill is partially paid',
+    example: true,
+  })
+  isPartiallyPaid: boolean;
+
+  @ApiProperty({
+    description: 'Whether the bill is fully paid',
+    example: false,
+  })
+  isFullyPaid: boolean;
+
+  @ApiProperty({
+    description: 'The date when the bill was created',
+    example: '2024-03-15T00:00:00Z',
+  })
+  createdAt: Date;
+
+  @ApiProperty({
+    description: 'The date when the bill was last updated',
+    example: '2024-03-16T00:00:00Z',
+    required: false,
+  })
+  updatedAt?: Date;
+}