refactor: document api endpoints

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

@@ -10,7 +10,7 @@ import {
 import { BranchesApplication } from './BranchesApplication.service';
 import { ICreateBranchDTO, IEditBranchDTO } from './Branches.types';
 import { PublicRoute } from '../Auth/Jwt.guard';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
 
 @Controller('branches')
 @ApiTags('branches')
@@ -20,42 +20,75 @@ export class BranchesController {
 
   @Get()
   @ApiOperation({ summary: 'Retrieves the branches.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The branches have been successfully retrieved.',
+  })
   getBranches() {
     return this.branchesApplication.getBranches();
   }
 
   @Get(':id')
   @ApiOperation({ summary: 'Retrieves the branch details.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The branch details have been successfully retrieved.',
+  })
+  @ApiResponse({ status: 404, description: 'The branch not found.' })
   getBranch(@Param('id') id: string) {
     return this.branchesApplication.getBranch(Number(id));
   }
 
   @Post()
   @ApiOperation({ summary: 'Create a new branch.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The branch has been successfully created.',
+  })
+  @ApiResponse({ status: 404, description: 'The branch not found.' })
   createBranch(@Body() createBranchDTO: ICreateBranchDTO) {
     return this.branchesApplication.createBranch(createBranchDTO);
   }
 
   @Put(':id')
   @ApiOperation({ summary: 'Edit the given branch.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The branch has been successfully edited.',
+  })
+  @ApiResponse({ status: 404, description: 'The branch not found.' })
   editBranch(@Param('id') id: string, @Body() editBranchDTO: IEditBranchDTO) {
     return this.branchesApplication.editBranch(Number(id), editBranchDTO);
   }
 
   @Delete(':id')
   @ApiOperation({ summary: 'Delete the given branch.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The branch has been successfully deleted.',
+  })
+  @ApiResponse({ status: 404, description: 'The branch not found.' })
   deleteBranch(@Param('id') id: string) {
     return this.branchesApplication.deleteBranch(Number(id));
   }
 
   @Post('activate')
   @ApiOperation({ summary: 'Activate the branches feature.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The branches feature has been successfully activated.',
+  })
   activateBranches() {
     return this.branchesApplication.activateBranches();
   }
 
   @Put(':id/mark-as-primary')
   @ApiOperation({ summary: 'Mark the given branch as primary.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The branch has been successfully marked as primary.',
+  })
+  @ApiResponse({ status: 404, description: 'The branch not found.' })
   markBranchAsPrimary(@Param('id') id: string) {
     return this.branchesApplication.markBranchAsPrimary(Number(id));
   }

packages/server-nest/src/modules/Items/Item.controller.ts

@@ -8,12 +8,14 @@ import {
   Patch,
   Get,
   Put,
+  Query,
 } from '@nestjs/common';
 import { TenantController } from '../Tenancy/Tenant.controller';
 import { SubscriptionGuard } from '../Subscription/interceptors/Subscription.guard';
 import { PublicRoute } from '../Auth/Jwt.guard';
 import { ItemsApplicationService } from './ItemsApplication.service';
 import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+import { IItemsFilter } from './types/Items.types';
 
 @Controller('/items')
 @UseGuards(SubscriptionGuard)
@@ -24,6 +26,16 @@ export class ItemsController extends TenantController {
     super();
   }
 
+  @Get()
+  @ApiOperation({ summary: 'Retrieves the item list.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The item list has been successfully retrieved.',
+  })
+  async getItems(@Query() filterDTO: IItemsFilter): Promise<any> {
+    return this.itemsApplication.getItems(filterDTO);
+  }
+
   /**
    * Edit item.
    * @param id - The item id.
@@ -36,6 +48,7 @@ export class ItemsController extends TenantController {
     status: 200,
     description: 'The item has been successfully updated.',
   })
+  @ApiResponse({ status: 404, description: 'The item not found.' })
   // @UsePipes(new ZodValidationPipe(createItemSchema))
   async editItem(
     @Param('id') id: string,
@@ -52,6 +65,10 @@ export class ItemsController extends TenantController {
    */
   @Post()
   @ApiOperation({ summary: 'Create a new item (product or service).' })
+  @ApiResponse({
+    status: 200,
+    description: 'The item has been successfully created.',
+  })
   // @UsePipes(new ZodValidationPipe(createItemSchema))
   async createItem(@Body() createItemDto: any): Promise<number> {
     return this.itemsApplication.createItem(createItemDto);
@@ -63,6 +80,11 @@ export class ItemsController extends TenantController {
    */
   @Delete(':id')
   @ApiOperation({ summary: 'Delete the given item (product or service).' })
+  @ApiResponse({
+    status: 200,
+    description: 'The item has been successfully deleted.',
+  })
+  @ApiResponse({ status: 404, description: 'The item not found.' })
   async deleteItem(@Param('id') id: string): Promise<void> {
     const itemId = parseInt(id, 10);
     return this.itemsApplication.deleteItem(itemId);
@@ -74,6 +96,11 @@ export class ItemsController extends TenantController {
    */
   @Patch(':id/inactivate')
   @ApiOperation({ summary: 'Inactivate the given item (product or service).' })
+  @ApiResponse({
+    status: 200,
+    description: 'The item has been successfully inactivated.',
+  })
+  @ApiResponse({ status: 404, description: 'The item not found.' })
   async inactivateItem(@Param('id') id: string): Promise<void> {
     console.log(id, 'XXXXXX');
 
@@ -87,6 +114,11 @@ export class ItemsController extends TenantController {
    */
   @Patch(':id/activate')
   @ApiOperation({ summary: 'Activate the given item (product or service).' })
+  @ApiResponse({
+    status: 200,
+    description: 'The item has been successfully activated.',
+  })
+  @ApiResponse({ status: 404, description: 'The item not found.' })
   async activateItem(@Param('id') id: string): Promise<void> {
     const itemId = parseInt(id, 10);
     return this.itemsApplication.activateItem(itemId);
@@ -98,6 +130,11 @@ export class ItemsController extends TenantController {
    */
   @Get(':id')
   @ApiOperation({ summary: 'Get the given item (product or service).' })
+  @ApiResponse({
+    status: 200,
+    description: 'The item has been successfully retrieved.',
+  })
+  @ApiResponse({ status: 404, description: 'The item not found.' })
   async getItem(@Param('id') id: string): Promise<any> {
     const itemId = parseInt(id, 10);
     return this.itemsApplication.getItem(itemId);
@@ -109,7 +146,9 @@ export class ItemsController extends TenantController {
    * @returns {Promise<any>}
    */
   @Get(':id/invoices')
-  @ApiOperation({ summary: 'Retrieves the item associated invoices transactions.' })
+  @ApiOperation({
+    summary: 'Retrieves the item associated invoices transactions.',
+  })
   async getItemInvoicesTransactions(@Param('id') id: string): Promise<any> {
     const itemId = parseInt(id, 10);
     return this.itemsApplication.getItemInvoicesTransactions(itemId);
@@ -121,7 +160,9 @@ export class ItemsController extends TenantController {
    * @returns {Promise<any>}
    */
   @Get(':id/bills')
-  @ApiOperation({ summary: 'Retrieves the item associated bills transactions.' })
+  @ApiOperation({
+    summary: 'Retrieves the item associated bills transactions.',
+  })
   async getItemBillTransactions(@Param('id') id: string): Promise<any> {
     const itemId = parseInt(id, 10);
     return this.itemsApplication.getItemBillTransactions(itemId);
@@ -133,7 +174,14 @@ export class ItemsController extends TenantController {
    * @returns {Promise<any>}
    */
   @Get(':id/estimates')
-  @ApiOperation({ summary: 'Retrieves the item associated estimates transactions.' })
+  @ApiOperation({
+    summary: 'Retrieves the item associated estimates transactions.',
+  })
+  @ApiResponse({
+    status: 200,
+    description: 'The item associated estimate transactions have been successfully retrieved.',
+  })
+  @ApiResponse({ status: 404, description: 'The item not found.' })
   async getItemEstimatesTransactions(@Param('id') id: string): Promise<any> {
     const itemId = parseInt(id, 10);
     return this.itemsApplication.getItemEstimatesTransactions(itemId);
@@ -145,7 +193,14 @@ export class ItemsController extends TenantController {
    * @returns {Promise<any>}
    */
   @Get(':id/receipts')
-  @ApiOperation({ summary: 'Retrieves the item associated receipts transactions.' })
+  @ApiOperation({
+    summary: 'Retrieves the item associated receipts transactions.',
+  })
+  @ApiResponse({
+    status: 200,
+    description: 'The item associated receipts transactions have been successfully retrieved.',
+  })
+  @ApiResponse({ status: 404, description: 'The item not found.' })
   async getItemReceiptTransactions(@Param('id') id: string): Promise<any> {
     const itemId = parseInt(id, 10);
     return this.itemsApplication.getItemReceiptsTransactions(itemId);

packages/server-nest/src/modules/ManualJournals/ManualJournals.controller.ts

@@ -3,8 +3,6 @@ import {
   Controller,
   Delete,
   Get,
-  HttpCode,
-  HttpStatus,
   Param,
   Post,
   Put,
@@ -12,7 +10,7 @@ import {
 import { ManualJournalsApplication } from './ManualJournalsApplication.service';
 import { IManualJournalDTO } from './types/ManualJournals.types';
 import { PublicRoute } from '../Auth/Jwt.guard';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
 
 @Controller('manual-journals')
 @ApiTags('manual-journals')
@@ -28,6 +26,11 @@ export class ManualJournalsController {
 
   @Put(':id')
   @ApiOperation({ summary: 'Edit the given manual journal.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The manual journal has been successfully edited.',
+  })
+  @ApiResponse({ status: 404, description: 'The manual journal not found.' })
   public editManualJournal(
     @Param('id') manualJournalId: number,
     @Body() manualJournalDTO: IManualJournalDTO,
@@ -40,19 +43,33 @@ export class ManualJournalsController {
 
   @Delete(':id')
   @ApiOperation({ summary: 'Delete the given manual journal.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The manual journal has been successfully deleted.',
+  })
+  @ApiResponse({ status: 404, description: 'The manual journal not found.' })
   public deleteManualJournal(@Param('id') manualJournalId: number) {
     return this.manualJournalsApplication.deleteManualJournal(manualJournalId);
   }
 
   @Put(':id/publish')
   @ApiOperation({ summary: 'Publish the given manual journal.' })
-  @HttpCode(HttpStatus.OK)
+  @ApiResponse({
+    status: 200,
+    description: 'The manual journal has been successfully published.',
+  })
+  @ApiResponse({ status: 404, description: 'The manual journal not found.' })
   public publishManualJournal(@Param('id') manualJournalId: number) {
     return this.manualJournalsApplication.publishManualJournal(manualJournalId);
   }
 
   @Get(':id')
   @ApiOperation({ summary: 'Retrieves the manual journal details.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The manual journal details have been successfully retrieved.',
+  })
+  @ApiResponse({ status: 404, description: 'The manual journal not found.' })
   public getManualJournal(@Param('id') manualJournalId: number) {
     return this.manualJournalsApplication.getManualJournal(manualJournalId);
   }

packages/server-nest/src/modules/PdfTemplate/PdfTemplates.controller.ts

@@ -10,7 +10,7 @@ import {
 import { PdfTemplateApplication } from './PdfTemplate.application';
 import { ICreateInvoicePdfTemplateDTO, IEditPdfTemplateDTO } from './types';
 import { PublicRoute } from '../Auth/Jwt.guard';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
 
 @Controller('pdf-templates')
 @ApiTags('pdf-templates')
@@ -22,6 +22,10 @@ export class PdfTemplatesController {
 
   @Post()
   @ApiOperation({ summary: 'Create a new PDF template.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The PDF template has been successfully created.',
+  })
   async createPdfTemplate(
     @Body('templateName') templateName: string,
     @Body('resource') resource: string,
@@ -36,24 +40,43 @@ export class PdfTemplatesController {
 
   @Delete(':id')
   @ApiOperation({ summary: 'Delete the given PDF template.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The PDF template has been successfully deleted.',
+  })
+  @ApiResponse({ status: 404, description: 'The PDF template not found.' })
   async deletePdfTemplate(@Param('id') templateId: number) {
     return this.pdfTemplateApplication.deletePdfTemplate(templateId);
   }
 
   @Get(':id')
   @ApiOperation({ summary: 'Retrieves the PDF template details.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The PDF template details have been successfully retrieved.',
+  })
+  @ApiResponse({ status: 404, description: 'The PDF template not found.' })
   async getPdfTemplate(@Param('id') templateId: number) {
     return this.pdfTemplateApplication.getPdfTemplate(templateId);
   }
 
   @Get()
   @ApiOperation({ summary: 'Retrieves the PDF templates.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The PDF templates have been successfully retrieved.',
+  })
   async getPdfTemplates(@Body('resource') resource: string) {
     return this.pdfTemplateApplication.getPdfTemplates(resource);
   }
 
   @Put(':id')
   @ApiOperation({ summary: 'Edit the given PDF template.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The PDF template has been successfully edited.',
+  })
+  @ApiResponse({ status: 404, description: 'The PDF template not found.' })
   async editPdfTemplate(
     @Param('id') templateId: number,
     @Body() editDTO: IEditPdfTemplateDTO,
@@ -63,6 +86,11 @@ export class PdfTemplatesController {
 
   @Put(':id/assign-default')
   @ApiOperation({ summary: 'Assign the given PDF template as default.' })
+  @ApiResponse({
+    status: 200,
+    description: 'The PDF template has been successfully assigned as default.',
+  })
+  @ApiResponse({ status: 404, description: 'The PDF template not found.' })
   async assignPdfTemplateAsDefault(@Param('id') templateId: number) {
     return this.pdfTemplateApplication.assignPdfTemplateAsDefault(templateId);
   }