feat: add swagger docs for responses

packages/server/src/modules/TaxRates/TaxRate.controller.ts

@@ -8,22 +8,42 @@ import {
   Put,
 } from '@nestjs/common';
 import { TaxRatesApplication } from './TaxRate.application';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+  ApiExtraModels,
+  ApiOperation,
+  ApiResponse,
+  ApiTags,
+  getSchemaPath,
+} from '@nestjs/swagger';
 import { CreateTaxRateDto, EditTaxRateDto } from './dtos/TaxRate.dto';
+import { TaxRateResponseDto } from './dtos/TaxRateResponse.dto';
 
 @Controller('tax-rates')
 @ApiTags('Tax Rates')
+@ApiExtraModels(TaxRateResponseDto)
 export class TaxRatesController {
   constructor(private readonly taxRatesApplication: TaxRatesApplication) {}
 
   @Post()
   @ApiOperation({ summary: 'Create a new tax rate.' })
+  @ApiResponse({
+    status: 201,
+    description: 'The tax rate has been successfully created.',
+    schema: { $ref: getSchemaPath(TaxRateResponseDto) },
+  })
   public createTaxRate(@Body() createTaxRateDTO: CreateTaxRateDto) {
     return this.taxRatesApplication.createTaxRate(createTaxRateDTO);
   }
 
   @Put(':id')
   @ApiOperation({ summary: 'Edit the given tax rate.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The tax rate has been successfully updated.',
+    schema: {
+      $ref: getSchemaPath(TaxRateResponseDto),
+    },
+  })
   public editTaxRate(
     @Param('id') taxRateId: number,
     @Body() editTaxRateDTO: EditTaxRateDto,
@@ -33,30 +53,68 @@ export class TaxRatesController {
 
   @Delete(':id')
   @ApiOperation({ summary: 'Delete the given tax rate.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The tax rate has been successfully deleted.',
+    schema: {
+      $ref: getSchemaPath(TaxRateResponseDto),
+    },
+  })
   public deleteTaxRate(@Param('id') taxRateId: number) {
     return this.taxRatesApplication.deleteTaxRate(taxRateId);
   }
 
   @Get(':id')
   @ApiOperation({ summary: 'Retrieves the tax rate details.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The tax rate details have been successfully retrieved.',
+    schema: {
+      $ref: getSchemaPath(TaxRateResponseDto),
+    },
+  })
   public getTaxRate(@Param('id') taxRateId: number) {
     return this.taxRatesApplication.getTaxRate(taxRateId);
   }
 
   @Get()
   @ApiOperation({ summary: 'Retrieves the tax rates.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The tax rates have been successfully retrieved.',
+    schema: {
+      type: 'array',
+      items: {
+        $ref: getSchemaPath(TaxRateResponseDto),
+      },
+    },
+  })
   public getTaxRates() {
     return this.taxRatesApplication.getTaxRates();
   }
 
   @Put(':id/activate')
   @ApiOperation({ summary: 'Activate the given tax rate.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The tax rate has been successfully activated.',
+    schema: {
+      $ref: getSchemaPath(TaxRateResponseDto),
+    },
+  })
   public activateTaxRate(@Param('id') taxRateId: number) {
     return this.taxRatesApplication.activateTaxRate(taxRateId);
   }
 
   @Put(':id/inactivate')
   @ApiOperation({ summary: 'Inactivate the given tax rate.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The tax rate has been successfully inactivated.',
+    schema: {
+      $ref: getSchemaPath(TaxRateResponseDto),
+    },
+  })
   public inactivateTaxRate(@Param('id') taxRateId: number) {
     return this.taxRatesApplication.inactivateTaxRate(taxRateId);
   }

packages/server/src/modules/TaxRates/dtos/TaxRateResponse.dto.ts

@@ -0,0 +1,77 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class TaxRateResponseDto {
+  @ApiProperty({
+    description: 'The unique identifier of the tax rate',
+    example: 1,
+  })
+  id: number;
+
+  @ApiProperty({
+    description: 'The name of the tax rate',
+    example: 'VAT',
+  })
+  name: string;
+
+  @ApiProperty({
+    description:
+      'The formatted name of the tax rate including the rate percentage',
+    example: 'VAT [10%]',
+  })
+  nameFormatted: string;
+
+  @ApiProperty({
+    description: 'The code of the tax rate',
+    example: 'VAT',
+  })
+  code: string;
+
+  @ApiProperty({
+    description: 'The rate of the tax rate as a decimal number',
+    example: 10,
+  })
+  rate: number;
+
+  @ApiProperty({
+    description: 'The formatted rate of the tax rate with percentage symbol',
+    example: '10%',
+  })
+  rateFormatted: string;
+
+  @ApiProperty({
+    description: 'The description of the tax rate',
+    example: 'Value Added Tax',
+    required: false,
+  })
+  description?: string;
+
+  @ApiProperty({
+    description: 'Whether the tax is non-recoverable',
+    example: false,
+  })
+  isNonRecoverable: boolean;
+
+  @ApiProperty({
+    description: 'Whether the tax is compound',
+    example: false,
+  })
+  isCompound: boolean;
+
+  @ApiProperty({
+    description: 'Whether the tax rate is active',
+    example: true,
+  })
+  active: boolean;
+
+  @ApiProperty({
+    description: 'The date when the tax rate was created',
+    example: '2024-03-20T10:00:00Z',
+  })
+  createdAt: Date;
+
+  @ApiProperty({
+    description: 'The date when the tax rate was last updated',
+    example: '2024-03-20T10:00:00Z',
+  })
+  updatedAt: Date;
+}