feat: add swagger docs for responses

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

@@ -9,10 +9,18 @@ import {
 } from '@nestjs/common';
 import { BranchesApplication } from './BranchesApplication.service';
 import { CreateBranchDto, EditBranchDto } from './dtos/Branch.dto';
-import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+import {
+  ApiExtraModels,
+  ApiOperation,
+  ApiResponse,
+  ApiTags,
+  getSchemaPath,
+} from '@nestjs/swagger';
+import { BranchResponseDto } from './dtos/BranchResponse.dto';
 
 @Controller('branches')
 @ApiTags('Branches')
+@ApiExtraModels(BranchResponseDto)
 export class BranchesController {
   constructor(private readonly branchesApplication: BranchesApplication) {}
 
@@ -21,6 +29,12 @@ export class BranchesController {
   @ApiResponse({
     status: 200,
     description: 'The branches have been successfully retrieved.',
+    schema: {
+      type: 'array',
+      items: {
+        $ref: getSchemaPath(BranchResponseDto),
+      },
+    },
   })
   getBranches() {
     return this.branchesApplication.getBranches();
@@ -31,6 +45,9 @@ export class BranchesController {
   @ApiResponse({
     status: 200,
     description: 'The branch details have been successfully retrieved.',
+    schema: {
+      $ref: getSchemaPath(BranchResponseDto),
+    },
   })
   @ApiResponse({ status: 404, description: 'The branch not found.' })
   getBranch(@Param('id') id: string) {
@@ -42,6 +59,9 @@ export class BranchesController {
   @ApiResponse({
     status: 200,
     description: 'The branch has been successfully created.',
+    schema: {
+      $ref: getSchemaPath(BranchResponseDto),
+    },
   })
   @ApiResponse({ status: 404, description: 'The branch not found.' })
   createBranch(@Body() createBranchDTO: CreateBranchDto) {
@@ -53,6 +73,9 @@ export class BranchesController {
   @ApiResponse({
     status: 200,
     description: 'The branch has been successfully edited.',
+    schema: {
+      $ref: getSchemaPath(BranchResponseDto),
+    },
   })
   @ApiResponse({ status: 404, description: 'The branch not found.' })
   editBranch(@Param('id') id: string, @Body() editBranchDTO: EditBranchDto) {
@@ -90,6 +113,9 @@ export class BranchesController {
   @ApiResponse({
     status: 200,
     description: 'The branch has been successfully marked as primary.',
+    schema: {
+      $ref: getSchemaPath(BranchResponseDto),
+    },
   })
   @ApiResponse({ status: 404, description: 'The branch not found.' })
   markBranchAsPrimary(@Param('id') id: string) {

packages/server/src/modules/Branches/dtos/BranchResponse.dto.ts

@@ -0,0 +1,75 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class BranchResponseDto {
+  @ApiProperty({
+    description: 'Branch ID',
+    example: 1,
+  })
+  id: number;
+
+  @ApiProperty({
+    description: 'Branch name',
+    example: 'Main Branch',
+  })
+  name: string;
+
+  @ApiProperty({
+    description: 'Branch code',
+    example: 'BR001',
+  })
+  code: string;
+
+  @ApiProperty({
+    description: 'Branch address',
+    example: '123 Main Street',
+  })
+  address: string;
+
+  @ApiProperty({
+    description: 'Branch city',
+    example: 'New York',
+  })
+  city: string;
+
+  @ApiProperty({
+    description: 'Branch country',
+    example: 'USA',
+  })
+  country: string;
+
+  @ApiProperty({
+    description: 'Branch phone number',
+    example: '+1-555-123-4567',
+  })
+  phoneNumber: string;
+
+  @ApiProperty({
+    description: 'Branch email',
+    example: 'branch@example.com',
+  })
+  email: string;
+
+  @ApiProperty({
+    description: 'Branch website',
+    example: 'https://www.example.com/branch',
+  })
+  website: string;
+
+  @ApiProperty({
+    description: 'Whether this is the primary branch',
+    example: true,
+  })
+  primary: boolean;
+
+  @ApiProperty({
+    description: 'Creation timestamp',
+    example: '2024-03-20T10:00:00Z',
+  })
+  createdAt: Date;
+
+  @ApiProperty({
+    description: 'Last update timestamp',
+    example: '2024-03-20T10:00:00Z',
+  })
+  updatedAt: Date;
+}