feat(swagger): Enhance API documentation with detailed @ApiBody decor…

…ators - Implemented comprehensive @ApiBody decorators for required endpoints - Added explicit schema and example values to improve Swagger documentation - Enhanced API documentation for better developer understanding and testing
IndustryFusion · Dec 17, 2024 · f778a10 · f778a10
1 parent c1a270d
commit f778a10
Show file tree

Hide file tree

Showing 5 changed files with 332 additions and 1 deletion.
diff --git a/backend/src/endpoints/asset/asset.controller.ts b/backend/src/endpoints/asset/asset.controller.ts
@@ -16,12 +16,54 @@
 
 import { Controller, Get, Post, Body, Patch, Param, Delete } from '@nestjs/common';
 import { AssetService } from './asset.service';
+import { ApiBody } from '@nestjs/swagger';
 
 @Controller('asset')
 export class AssetController {
   constructor(private readonly assetService: AssetService) {}
 
   @Post()
+  @ApiBody({
+    description: 'Asset creation details',
+    required: true,
+    schema: {
+      type: 'object',
+      properties: {
+        dataspace_code: {
+          type: 'string',
+          example: 'DS001',
+        },
+        region_code: {
+          type: 'string',
+          example: 'US-WEST',
+        },
+        object_type_code: {
+          type: 'string',
+          example: 'TYPE123',
+        },
+        object_sub_type_code: {
+          type: 'string',
+          example: 'SUBTYPE456',
+        },
+        machine_serial_number: {
+          type: 'string',
+          example: 'SN1234567890',
+        },
+        registration_number: {
+          type: 'string',
+          example: 'REG12345',
+        },
+      },
+      required: [
+        'dataspace_code',
+        'region_code',
+        'object_type_code',
+        'object_sub_type_code',
+        'machine_serial_number',
+        'registration_number',
+      ],
+    },
+  })  
   create(@Body() data: any) {
     return this.assetService.create(data);
   }
@@ -37,6 +79,39 @@ export class AssetController {
   }
 
   @Patch(':id')
+  @ApiBody({
+    description: 'Asset creation details',
+    required: true,
+    schema: {
+      type: 'object',
+      properties: {
+        dataspace_code: {
+          type: 'string',
+          example: 'DS001',
+        },
+        region_code: {
+          type: 'string',
+          example: 'US-WEST',
+        },
+        object_type_code: {
+          type: 'string',
+          example: 'TYPE123',
+        },
+        object_sub_type_code: {
+          type: 'string',
+          example: 'SUBTYPE456',
+        },
+        machine_serial_number: {
+          type: 'string',
+          example: 'SN1234567890',
+        },
+        registration_number: {
+          type: 'string',
+          example: 'REG12345',
+        },
+      },
+    },
+  })  
   update(@Param('id') id: string, @Body() data: any) {
     return this.assetService.update(id);
   }

diff --git a/backend/src/endpoints/certificate/certificate.controller.ts b/backend/src/endpoints/certificate/certificate.controller.ts
@@ -1,13 +1,32 @@
 import { Controller, Get, Post, Body, Patch, Param, Delete } from '@nestjs/common';
 import { CertificateService } from './certificate.service';
 import { CreateCompanyCertificateDto, CreateAssetCertificateDto } from './dto/create-certificate.dto';
+import { ApiBody } from '@nestjs/swagger';
 
 
 @Controller('certificate')
 export class CertificateController {
   constructor(private readonly certificateService: CertificateService) {}
-
   @Post('create-company-certificate')
+  @ApiBody({
+    description: 'Create Company Certificate details',
+    required: true,
+    schema: {
+      type: 'object',
+      properties: {
+        company_ifric_id: {
+          type: 'string',
+          example: 'C987654321',
+        },
+        expiry: {
+          type: 'string',
+          format: 'date-time',
+          example: '2025-12-31T23:59:59.999Z',
+        },
+      },
+      required: ['company_ifric_id', 'expiry'],
+    },
+  })  
   async generateCompanyCertificate(@Body() data: CreateCompanyCertificateDto) {
     try {
       return await this.certificateService.generateCompanyCertificate(data.company_ifric_id, new Date(data.expiry));
@@ -17,6 +36,25 @@ export class CertificateController {
   }
 
   @Post('create-asset-certificate')
+  @ApiBody({
+    description: 'Create Asset Certificate details',
+    required: true,
+    schema: {
+      type: 'object',
+      properties: {
+        asset_ifric_id: {
+          type: 'string',
+          example: 'A123456789',
+        },
+        expiry: {
+          type: 'string',
+          format: 'date-time',
+          example: '2025-12-31T23:59:59.999Z',
+        },
+      },
+      required: ['asset_ifric_id', 'expiry'],
+    },
+  })  
   async generateAssetCertificate(@Body() data: CreateAssetCertificateDto) {
     try {
       return await this.certificateService.generateAssetCertificate(data.asset_ifric_id, new Date(data.expiry));
@@ -26,6 +64,24 @@ export class CertificateController {
   }
 
   @Post('verify-company-certificate')
+  @ApiBody({
+    schema: {
+      type: 'object',
+      properties: {
+        company_ifric_id: { 
+          type: 'string', 
+          description: 'Unique identifier for the company',
+          example: 'IFRIC12345'
+        },
+        certificate_data: { 
+          type: 'string', 
+          description: 'Certificate data to be verified',
+          example: 'base64encodedcertificatestring'
+        }
+      },
+      required: ['company_ifric_id', 'certificate_data']
+    }
+  })  
   async verifyCertificate(@Body() data: {company_ifric_id: string, certificate_data: string}) {
     try {
       return await this.certificateService.verifyCertificate(data.certificate_data);
@@ -35,6 +91,24 @@ export class CertificateController {
   }
 
   @Post('verify-asset-certificate')
+  @ApiBody({
+    schema: {
+      type: 'object',
+      properties: {
+        asset_ifric_id: { 
+          type: 'string', 
+          description: 'Unique identifier for the asset',
+          example: 'Asset12345'
+        },
+        certificate_data: { 
+          type: 'string', 
+          description: 'Certificate data to be verified',
+          example: 'base64encodedcertificatestring'
+        }
+      },
+      required: ['asset_ifric_id', 'certificate_data']
+    }
+  })  
   async verifyAssetCertificate(@Body() data: {asset_ifric_id: string, certificate_data: string}) {
     try {
       return await this.certificateService.verifyCertificate(data.certificate_data);

diff --git a/backend/src/endpoints/company/company.controller.ts b/backend/src/endpoints/company/company.controller.ts
@@ -16,12 +16,104 @@
 
 import { Controller, Get, Post, Body, Patch, Param, Delete } from '@nestjs/common';
 import { CompanyService } from './company.service';
+import { ApiBody } from '@nestjs/swagger';
 
 @Controller('company')
 export class CompanyController {
   constructor(private readonly companyService: CompanyService) {}
 
   @Post()
+  @ApiBody({
+    description: 'Details for creating a company',
+    required: true,
+    schema: {
+      type: 'object',
+      properties: {
+        company_name: { 
+          type: 'string', 
+          example: 'Example Company Ltd.' 
+        },
+        registration_number: { 
+          type: 'string', 
+          example: 'REG123456' 
+        },
+        company_ifric_id: { 
+          type: 'string', 
+          example: 'IFRIC54321' 
+        },
+        address_1: { 
+          type: 'string', 
+          example: '123 Main Street' 
+        },
+        city: { 
+          type: 'string', 
+          example: 'New York' 
+        },
+        country: { 
+          type: 'string', 
+          example: 'USA' 
+        },
+        zip: { 
+          type: 'string', 
+          example: '10001' 
+        },
+        admin_name: { 
+          type: 'string', 
+          example: 'John Admin' 
+        },
+        position: { 
+          type: 'string', 
+          example: 'CEO' 
+        },
+        email: { 
+          type: 'string', 
+          example: '[email protected]' 
+        },
+        password: { 
+          type: 'string', 
+          example: 'strongpassword123' 
+        },
+        company_size: { 
+          type: 'string', 
+          example: '100-500' 
+        },
+        company_category_id: { 
+          type: 'number', 
+          example: 1 
+        },
+        company_category: { 
+          type: 'string', 
+          example: 'IT Services' 
+        },
+        meta_data: { 
+          type: 'object', 
+          additionalProperties: true,
+          example: { industry: 'Technology', revenue: '1M+' } 
+        },
+        company_domain: { 
+          type: 'string', 
+          example: 'example.com' 
+        }
+      },
+      required: [
+        'company_name',
+        'registration_number',
+        'company_ifric_id',
+        'address_1',
+        'city',
+        'country',
+        'zip',
+        'admin_name',
+        'position',
+        'email',
+        'password',
+        'company_size',
+        'company_category',
+        'meta_data',
+        'company_domain',
+      ],
+    },
+  })
   create(@Body() data: any) {
     return this.companyService.create(data);
   }

diff --git a/backend/src/endpoints/contract/contract.controller.ts b/backend/src/endpoints/contract/contract.controller.ts
@@ -1,17 +1,60 @@
 import { Controller, Get, Post, Body, Patch, Param, Delete } from '@nestjs/common';
 import { ContractService } from './contract.service';
 import { CreateContractDto, CreateBindingDto } from './dto/create-contract.dto';
+import { ApiBody } from '@nestjs/swagger';
 
 @Controller('contract')
 export class ContractController {
   constructor(private readonly contractService: ContractService) {}
 
   @Post('/binding')
+  @ApiBody({
+    description: 'Create Binding details',
+    required: true,
+    schema: {
+      type: 'object',
+      properties: {
+        data_consumer_company_ifric_id: {
+          type: 'string',
+          example: 'C123456789',
+        },
+        data_provider_company_ifric_id: {
+          type: 'string',
+          example: 'P987654321',
+        },
+        binding_datetime_string: {
+          type: 'string',
+          format: 'date-time',
+          example: '2025-12-31T10:00:00Z',
+        },
+      },
+      required: ['data_consumer_company_ifric_id', 'data_provider_company_ifric_id', 'binding_datetime_string'],
+    },
+  })  
   createBinding(@Body() createBindingDto: CreateBindingDto) {  
     return this.contractService.createBinding(createBindingDto);
   }
 
   @Post()
+  @ApiBody({
+    description: 'Create Contract details',
+    required: true,
+    schema: {
+      type: 'object',
+      properties: {
+        data_consumer_company_ifric_id: {
+          type: 'string',
+          example: 'C123456789',
+        },
+        contract_datetime_string: {
+          type: 'string',
+          format: 'date-time',
+          example: '2025-12-31T10:00:00Z',
+        },
+      },
+      required: ['data_consumer_company_ifric_id', 'contract_datetime_string'],
+    },
+  })  
   createContract(@Body() createContractDto: CreateContractDto) {
     return this.contractService.createContract(createContractDto);
   }