From 26c1f118c1dc62d4125ed6a193b16eb4a7e85dd9 Mon Sep 17 00:00:00 2001 From: Ahmed Bouhuolia Date: Thu, 19 Jun 2025 00:49:43 +0200 Subject: [PATCH] feat: more response docs --- .../modules/Accounts/Accounts.controller.ts | 7 ++ .../Accounts/dtos/AccountTypeResponse.dto.ts | 51 ++++++++++ .../InventoryAdjustments.controller.ts | 4 + .../src/modules/Items/Item.controller.ts | 65 +++++-------- .../Items/dtos/ItemBillsResponse.dto.ts | 94 +++++++++++++++++++ .../Items/dtos/ItemEstimatesResponse.dto.ts | 71 ++++++++++++++ .../Items/dtos/ItemInvoiceResponse.dto.ts | 78 +++++++++++++++ .../Items/dtos/ItemReceiptsResponse.dto.ts | 76 +++++++++++++++ 8 files changed, 405 insertions(+), 41 deletions(-) create mode 100644 packages/server/src/modules/Accounts/dtos/AccountTypeResponse.dto.ts create mode 100644 packages/server/src/modules/Items/dtos/ItemBillsResponse.dto.ts create mode 100644 packages/server/src/modules/Items/dtos/ItemEstimatesResponse.dto.ts create mode 100644 packages/server/src/modules/Items/dtos/ItemInvoiceResponse.dto.ts create mode 100644 packages/server/src/modules/Items/dtos/ItemReceiptsResponse.dto.ts diff --git a/packages/server/src/modules/Accounts/Accounts.controller.ts b/packages/server/src/modules/Accounts/Accounts.controller.ts index 6546ead11..a9a6b0e88 100644 --- a/packages/server/src/modules/Accounts/Accounts.controller.ts +++ b/packages/server/src/modules/Accounts/Accounts.controller.ts @@ -13,6 +13,7 @@ import { CreateAccountDTO } from './CreateAccount.dto'; import { EditAccountDTO } from './EditAccount.dto'; import { IAccountsFilter, IAccountsTransactionsFilter } from './Accounts.types'; import { + ApiExtraModels, ApiOperation, ApiParam, ApiResponse, @@ -20,9 +21,12 @@ import { getSchemaPath, } from '@nestjs/swagger'; import { AccountResponseDto } from './dtos/AccountResponse.dto'; +import { AccountTypeResponseDto } from './dtos/AccountTypeResponse.dto'; @Controller('accounts') @ApiTags('Accounts') +@ApiExtraModels(AccountResponseDto) +@ApiExtraModels(AccountTypeResponseDto) export class AccountsController { constructor(private readonly accountsApplication: AccountsApplication) {} @@ -112,6 +116,9 @@ export class AccountsController { @ApiResponse({ status: 200, description: 'The account types have been successfully retrieved.', + schema: { + $ref: getSchemaPath(AccountTypeResponseDto), + }, }) async getAccountTypes() { return this.accountsApplication.getAccountTypes(); diff --git a/packages/server/src/modules/Accounts/dtos/AccountTypeResponse.dto.ts b/packages/server/src/modules/Accounts/dtos/AccountTypeResponse.dto.ts new file mode 100644 index 000000000..d26f8c20b --- /dev/null +++ b/packages/server/src/modules/Accounts/dtos/AccountTypeResponse.dto.ts @@ -0,0 +1,51 @@ +import { ApiProperty, ApiExtraModels } from '@nestjs/swagger'; + +export class AccountTypeResponseDto { + @ApiProperty({ + description: 'The display label for the account type', + example: 'Cash', + }) + label: string; + + @ApiProperty({ + description: 'The unique key for the account type', + example: 'cash', + }) + key: string; + + @ApiProperty({ + description: 'The normal balance type for the account', + example: 'debit', + }) + normal: string; + + @ApiProperty({ + description: 'The parent type of the account', + example: 'current-asset', + }) + parentType: string; + + @ApiProperty({ + description: 'The root type of the account', + example: 'asset', + }) + rootType: string; + + @ApiProperty({ + description: 'Whether the account type supports multiple currencies', + example: true, + }) + multiCurrency: boolean; + + @ApiProperty({ + description: 'Whether the account type appears on the balance sheet', + example: true, + }) + balanceSheet: boolean; + + @ApiProperty({ + description: 'Whether the account type appears on the income sheet', + example: false, + }) + incomeSheet: boolean; +} diff --git a/packages/server/src/modules/InventoryAdjutments/InventoryAdjustments.controller.ts b/packages/server/src/modules/InventoryAdjutments/InventoryAdjustments.controller.ts index 85d374d6b..a8a4ef7af 100644 --- a/packages/server/src/modules/InventoryAdjutments/InventoryAdjustments.controller.ts +++ b/packages/server/src/modules/InventoryAdjutments/InventoryAdjustments.controller.ts @@ -62,6 +62,10 @@ export class InventoryAdjustmentsController { @ApiResponse({ status: 200, description: 'The inventory adjustments have been successfully retrieved.', + schema: { + type: 'array', + items: { $ref: getSchemaPath(InventoryAdjustmentResponseDto) }, + }, }) public async getInventoryAdjustments( @Query() filterDTO: IInventoryAdjustmentsFilter, diff --git a/packages/server/src/modules/Items/Item.controller.ts b/packages/server/src/modules/Items/Item.controller.ts index 1a46fd444..f0193c4c0 100644 --- a/packages/server/src/modules/Items/Item.controller.ts +++ b/packages/server/src/modules/Items/Item.controller.ts @@ -27,12 +27,21 @@ import { CreateItemDto, EditItemDto } from './dtos/Item.dto'; import { GetItemsQueryDto } from './dtos/GetItemsQuery.dto'; import { ItemResponseDto } from './dtos/itemResponse.dto'; import { PaginatedResponseDto } from '@/common/dtos/PaginatedResults.dto'; +import { ItemInvoiceResponseDto } from './dtos/itemInvoiceResponse.dto'; +import { ItemEstimatesResponseDto } from './dtos/ItemEstimatesResponse.dto'; +import { ItemBillsResponseDto } from './dtos/itemBillsResponse.dto'; +import { ItemReceiptsResponseDto } from './dtos/ItemReceiptsResponse.dto'; @Controller('/items') @ApiTags('Items') @UseGuards(SubscriptionGuard) @ApiExtraModels(ItemResponseDto) @ApiExtraModels(PaginatedResponseDto) +@ApiExtraModels(ItemInvoiceResponseDto) +@ApiExtraModels(ItemEstimatesResponseDto) +@ApiExtraModels(ItemBillsResponseDto) +@ApiExtraModels(ItemEstimatesResponseDto) +@ApiExtraModels(ItemReceiptsResponseDto) export class ItemsController extends TenantController { constructor(private readonly itemsApplication: ItemsApplicationService) { super(); @@ -150,11 +159,6 @@ export class ItemsController extends TenantController { return this.itemsApplication.editItem(itemId, editItemDto); } - /** - * Create item. - * @param createItemDto - The item DTO. - * @returns The created item id. - */ @Post() @ApiOperation({ summary: 'Create a new item (product or service).' }) @ApiResponse({ @@ -166,10 +170,6 @@ export class ItemsController extends TenantController { return this.itemsApplication.createItem(createItemDto); } - /** - * Delete item. - * @param id - The item id. - */ @Delete(':id') @ApiOperation({ summary: 'Delete the given item (product or service).' }) @ApiResponse({ @@ -188,10 +188,6 @@ export class ItemsController extends TenantController { return this.itemsApplication.deleteItem(itemId); } - /** - * Inactivate item. - * @param id - The item id. - */ @Patch(':id/inactivate') @ApiOperation({ summary: 'Inactivate the given item (product or service).' }) @ApiResponse({ @@ -210,10 +206,6 @@ export class ItemsController extends TenantController { return this.itemsApplication.inactivateItem(itemId); } - /** - * Activate item. - * @param id - The item id. - */ @Patch(':id/activate') @ApiOperation({ summary: 'Activate the given item (product or service).' }) @ApiResponse({ @@ -232,10 +224,6 @@ export class ItemsController extends TenantController { return this.itemsApplication.activateItem(itemId); } - /** - * Get item. - * @param id - The item id. - */ @Get(':id') @ApiOperation({ summary: 'Get the given item (product or service).' }) @ApiResponse({ @@ -257,11 +245,6 @@ export class ItemsController extends TenantController { return this.itemsApplication.getItem(itemId); } - /** - * Retrieves the item associated invoices transactions. - * @param {string} id - * @returns {Promise} - */ @Get(':id/invoices') @ApiOperation({ summary: 'Retrieves the item associated invoices transactions.', @@ -270,6 +253,10 @@ export class ItemsController extends TenantController { status: 200, description: 'The item associated invoices transactions have been successfully retrieved.', + schema: { + type: 'array', + items: { $ref: getSchemaPath(ItemInvoiceResponseDto) }, + }, }) @ApiResponse({ status: 404, description: 'The item not found.' }) @ApiParam({ @@ -283,11 +270,6 @@ export class ItemsController extends TenantController { return this.itemsApplication.getItemInvoicesTransactions(itemId); } - /** - * Retrieves the item associated bills transactions. - * @param {string} id - * @returns {Promise} - */ @Get(':id/bills') @ApiOperation({ summary: 'Retrieves the item associated bills transactions.', @@ -296,6 +278,10 @@ export class ItemsController extends TenantController { status: 200, description: 'The item associated bills transactions have been successfully retrieved.', + schema: { + type: 'array', + items: { $ref: getSchemaPath(ItemBillsResponseDto) }, + }, }) @ApiResponse({ status: 404, description: 'The item not found.' }) @ApiParam({ @@ -309,11 +295,6 @@ export class ItemsController extends TenantController { return this.itemsApplication.getItemBillTransactions(itemId); } - /** - * Retrieves the item associated estimates transactions. - * @param {string} id - * @returns {Promise} - */ @Get(':id/estimates') @ApiOperation({ summary: 'Retrieves the item associated estimates transactions.', @@ -322,6 +303,10 @@ export class ItemsController extends TenantController { status: 200, description: 'The item associated estimate transactions have been successfully retrieved.', + schema: { + type: 'array', + items: { $ref: getSchemaPath(ItemEstimatesResponseDto) }, + }, }) @ApiResponse({ status: 404, description: 'The item not found.' }) @ApiParam({ @@ -335,11 +320,6 @@ export class ItemsController extends TenantController { return this.itemsApplication.getItemEstimatesTransactions(itemId); } - /** - * Retrieves the item associated receipts transactions. - * @param {string} id - * @returns {Promise} - */ @Get(':id/receipts') @ApiOperation({ summary: 'Retrieves the item associated receipts transactions.', @@ -348,6 +328,9 @@ export class ItemsController extends TenantController { status: 200, description: 'The item associated receipts transactions have been successfully retrieved.', + schema: { + $ref: getSchemaPath(ItemReceiptsResponseDto), + }, }) @ApiResponse({ status: 404, description: 'The item not found.' }) @ApiParam({ diff --git a/packages/server/src/modules/Items/dtos/ItemBillsResponse.dto.ts b/packages/server/src/modules/Items/dtos/ItemBillsResponse.dto.ts new file mode 100644 index 000000000..6839b1b20 --- /dev/null +++ b/packages/server/src/modules/Items/dtos/ItemBillsResponse.dto.ts @@ -0,0 +1,94 @@ +import { ApiProperty, ApiExtraModels } from '@nestjs/swagger'; + +@ApiExtraModels() +export class ItemBillsResponseDto { + @ApiProperty({ + example: 123, + description: 'The unique identifier of the bill.', + }) + billId: number; + + @ApiProperty({ + example: 'BILL-2024-001', + description: 'The bill number.', + }) + billNumber: string; + + @ApiProperty({ + example: 'REF-2024-001', + description: 'The reference number of the bill.', + }) + referenceNumber: string; + + @ApiProperty({ + example: '2024-06-01', + description: 'The date of the bill.', + }) + billDate: string; + + @ApiProperty({ + example: '01/06/2024', + description: 'The formatted date of the bill.', + }) + formattedBillDate: string; + + @ApiProperty({ + example: '2024-06-15', + description: 'The due date of the bill.', + }) + billDueDate: string; + + @ApiProperty({ + example: '15/06/2024', + description: 'The formatted due date of the bill.', + }) + formattedBillDueDate: string; + + @ApiProperty({ + example: 1000, + description: 'The amount of the bill item.', + }) + amount: number; + + @ApiProperty({ + example: '$1,000.00', + description: 'The formatted amount of the bill item.', + }) + formattedAmount: string; + + @ApiProperty({ + example: 5, + description: 'The quantity of the item in the bill.', + }) + quantity: number; + + @ApiProperty({ + example: '5', + description: 'The formatted quantity of the item in the bill.', + }) + formattedQuantity: string; + + @ApiProperty({ + example: 200, + description: 'The rate of the item in the bill.', + }) + rate: number; + + @ApiProperty({ + example: '$200.00', + description: 'The formatted rate of the item in the bill.', + }) + formattedRate: string; + + @ApiProperty({ + example: 'Acme Vendor', + description: 'The display name of the vendor.', + }) + vendorDisplayName: string; + + @ApiProperty({ + example: 'USD', + description: 'The currency code of the vendor.', + }) + vendorCurrencyCode: string; +} diff --git a/packages/server/src/modules/Items/dtos/ItemEstimatesResponse.dto.ts b/packages/server/src/modules/Items/dtos/ItemEstimatesResponse.dto.ts new file mode 100644 index 000000000..0bad355ec --- /dev/null +++ b/packages/server/src/modules/Items/dtos/ItemEstimatesResponse.dto.ts @@ -0,0 +1,71 @@ +import { ApiProperty } from '@nestjs/swagger'; +import { ApiExtraModels } from '@nestjs/swagger'; + +@ApiExtraModels() +export class ItemEstimatesResponseDto { + @ApiProperty({ + example: 123, + description: 'The unique identifier of the estimate.', + }) + estimateId: number; + + @ApiProperty({ example: 'EST-2024-001', description: 'The estimate number.' }) + estimateNumber: string; + + @ApiProperty({ + example: 'REF-2024-001', + description: 'The reference number for the estimate.', + }) + referenceNumber: string; + + @ApiProperty({ + example: '2024-06-01', + description: 'The date of the estimate.', + }) + estimateDate: string; + + @ApiProperty({ + example: '01/06/2024', + description: 'The formatted estimate date.', + }) + formattedEstimateDate: string; + + @ApiProperty({ example: 1000, description: 'The amount of the estimate.' }) + amount: number; + + @ApiProperty({ + example: '$1,000.00', + description: 'The formatted amount of the estimate.', + }) + formattedAmount: string; + + @ApiProperty({ example: 5, description: 'The quantity in the estimate.' }) + quantity: number; + + @ApiProperty({ + example: '5', + description: 'The formatted quantity in the estimate.', + }) + formattedQuantity: string; + + @ApiProperty({ example: 200, description: 'The rate in the estimate.' }) + rate: number; + + @ApiProperty({ + example: '$200.00', + description: 'The formatted rate in the estimate.', + }) + formattedRate: string; + + @ApiProperty({ + example: 'Acme Corp', + description: 'The display name of the customer.', + }) + customerDisplayName: string; + + @ApiProperty({ + example: 'USD', + description: 'The currency code of the customer.', + }) + customerCurrencyCode: string; +} diff --git a/packages/server/src/modules/Items/dtos/ItemInvoiceResponse.dto.ts b/packages/server/src/modules/Items/dtos/ItemInvoiceResponse.dto.ts new file mode 100644 index 000000000..ed39acd71 --- /dev/null +++ b/packages/server/src/modules/Items/dtos/ItemInvoiceResponse.dto.ts @@ -0,0 +1,78 @@ +import { ApiProperty, ApiExtraModels } from '@nestjs/swagger'; + +export class ItemInvoiceResponseDto { + @ApiProperty({ + example: 123, + description: 'The unique identifier of the invoice.', + }) + invoiceId: number; + + @ApiProperty({ example: 'INV-2024-001', description: 'The invoice number.' }) + invoiceNumber: string; + + @ApiProperty({ + example: 'REF-2024-001', + description: 'The reference number of the invoice.', + }) + referenceNumber: string; + + @ApiProperty({ + example: '2024-06-01', + description: 'The date of the invoice.', + }) + invoiceDate: string; + + @ApiProperty({ + example: '01/06/2024', + description: 'The formatted date of the invoice.', + }) + formattedInvoiceDate: string; + + @ApiProperty({ + example: 1000, + description: 'The amount of the invoice item.', + }) + amount: number; + + @ApiProperty({ + example: '$1,000.00', + description: 'The formatted amount of the invoice item.', + }) + formattedAmount: string; + + @ApiProperty({ + example: 5, + description: 'The quantity of the item in the invoice.', + }) + quantity: number; + + @ApiProperty({ + example: '5', + description: 'The formatted quantity of the item in the invoice.', + }) + formattedQuantity: string; + + @ApiProperty({ + example: 200, + description: 'The rate of the item in the invoice.', + }) + rate: number; + + @ApiProperty({ + example: '$200.00', + description: 'The formatted rate of the item in the invoice.', + }) + formattedRate: string; + + @ApiProperty({ + example: 'Acme Corp', + description: 'The display name of the customer.', + }) + customerDisplayName: string; + + @ApiProperty({ + example: 'USD', + description: 'The currency code of the customer.', + }) + customerCurrencyCode: string; +} diff --git a/packages/server/src/modules/Items/dtos/ItemReceiptsResponse.dto.ts b/packages/server/src/modules/Items/dtos/ItemReceiptsResponse.dto.ts new file mode 100644 index 000000000..b5e47a925 --- /dev/null +++ b/packages/server/src/modules/Items/dtos/ItemReceiptsResponse.dto.ts @@ -0,0 +1,76 @@ +import { ApiProperty, ApiExtraModels } from '@nestjs/swagger'; + +@ApiExtraModels() +export class ItemReceiptsResponseDto { + @ApiProperty({ + example: 123, + description: 'The unique identifier of the receipt.', + }) + receiptId: number; + + @ApiProperty({ example: 'RCPT-2024-001', description: 'The receipt number.' }) + receipNumber: string; + + @ApiProperty({ + example: 'REF-2024-001', + description: 'The reference number for the receipt.', + }) + referenceNumber: string; + + @ApiProperty({ + example: '2024-06-01', + description: 'The date of the receipt.', + }) + receiptDate: string; + + @ApiProperty({ + example: '01/06/2024', + description: 'The formatted date of the receipt.', + }) + formattedReceiptDate: string; + + @ApiProperty({ example: 1000, description: 'The amount for the receipt.' }) + amount: number; + + @ApiProperty({ + example: '$1,000.00', + description: 'The formatted amount for the receipt.', + }) + formattedAmount: string; + + @ApiProperty({ + example: 10, + description: 'The quantity of items in the receipt.', + }) + quantity: number; + + @ApiProperty({ + example: '10', + description: 'The formatted quantity of items in the receipt.', + }) + formattedQuantity: string; + + @ApiProperty({ + example: 100, + description: 'The rate per item in the receipt.', + }) + rate: number; + + @ApiProperty({ + example: '$100.00', + description: 'The formatted rate per item in the receipt.', + }) + formattedRate: string; + + @ApiProperty({ + example: 'John Doe', + description: 'The display name of the customer.', + }) + customerDisplayName: string; + + @ApiProperty({ + example: 'USD', + description: 'The currency code of the customer.', + }) + customerCurrencyCode: string; +}