Merge pull request #3082 from energywebfoundation/wpurdum/IssuerAPIDo…

…cumentation Add API examples and descriptions for Traceability DTOs
energywebfoundation · Nov 9, 2021 · c5fd701 · c5fd701
2 parents 1c1f7ac + f9dddff
commit c5fd701
Show file tree

Hide file tree

Showing 17 changed files with 58 additions and 57 deletions.
diff --git a/docs/traceability.md b/docs/traceability.md
@@ -24,5 +24,6 @@ Package contains all the facades and entities that concern the on-chain presence
 
 -   [ERC-1888](traceability/contracts/ERC1888/ERC1888.md)
 -   [Registry](traceability/contracts/Registry.md)
+-   [Registry Extended](traceability/contracts/RegistryExtended.md)
 -   [Issuer](traceability/contracts/Issuer.md)
 -   [PrivateIssuer](traceability/contracts/PrivateIssuer.md)
diff --git a/packages/traceability/issuer-api/src/pods/certificate/dto/batch-certificate-claim.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/dto/batch-certificate-claim.dto.ts
@@ -12,7 +12,7 @@ export class BatchCertificateClaimDTO
     @IsObject()
     claimData: IClaimData;
 
-    @ApiPropertyOptional({ type: String })
+    @ApiPropertyOptional({ type: String, description: "Public blockchain address", example: '0xd46aC0Bc23dB5e8AfDAAB9Ad35E9A3bA05E092E8' })
     @IsEthereumAddress()
     to?: string;
 }
diff --git a/packages/traceability/issuer-api/src/pods/certificate/dto/batch-certificate-transfer.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/dto/batch-certificate-transfer.dto.ts
@@ -10,16 +10,16 @@ export class BatchCertificateTransferDTO
     extends PickType(CertificateDTO, ['id'] as const)
     implements Omit<CertificateBatchOperations.BatchCertificateTransfer, 'amount'>
 {
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, description: "Public blockchain address", example: '0xd46aC0Bc23dB5e8AfDAAB9Ad35E9A3bA05E092E8' })
     @IsEthereumAddress()
     to: string;
 
-    @ApiPropertyOptional({ type: String })
+    @ApiPropertyOptional({ type: String, description: "Public blockchain address", example: '0xd46aC0Bc23dB5e8AfDAAB9Ad35E9A3bA05E092E8' })
     @IsOptional()
     @IsEthereumAddress()
     from?: string;
 
-    @ApiPropertyOptional({ type: String })
+    @ApiPropertyOptional({ type: String, example: "1000"})
     @IsOptional()
     @Validate(IntUnitsOfEnergy)
     amount?: string;

diff --git a/packages/traceability/issuer-api/src/pods/certificate/dto/certificate-ids.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/dto/certificate-ids.dto.ts
@@ -2,7 +2,7 @@ import { ApiProperty } from '@nestjs/swagger';
 import { IsInt, Min } from 'class-validator';
 
 export class CertificateIdsDTO {
-    @ApiProperty({ type: [Number] })
+    @ApiProperty({ type: [Number], description: "Array of Certificate Ids", example: [1, 2, 3] })
     @IsInt({ each: true })
     @Min(1, { each: true })
     ids: number[];

diff --git a/packages/traceability/issuer-api/src/pods/certificate/dto/certificate.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/dto/certificate.dto.ts
@@ -13,31 +13,31 @@ import { ClaimDTO } from './claim.dto';
 import { EnergyDTO } from './energy.dto';
 
 export class CertificateDTO {
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Certificate Id" })
     @IsInt()
     @Min(1)
     id: number;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "DeviceB-789"})
     @IsString()
     deviceId: string;
 
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Unix timestamp", example: 1636154471})
     @IsInt()
     @IsPositive()
     generationStartTime: number;
 
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Unix timestamp", example: 1636154471})
     @IsInt()
     @IsPositive()
     generationEndTime: number;
 
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Unix timestamp", example: 1636154471})
     @IsInt()
     @IsPositive()
     creationTime: number;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "Additional Details" })
     @IsString()
     metadata: string;
 
@@ -68,7 +68,7 @@ export class CertificateDTO {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     blockchain?: any;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "0x2b8da531e46cff1e217abc113495befac9384339feb10816b0f7f2ffa02fadd4"})
     creationTransactionHash?: string;
 
     @ApiPropertyOptional({ type: Boolean })

diff --git a/packages/traceability/issuer-api/src/pods/certificate/dto/claim-certificate.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/dto/claim-certificate.dto.ts
@@ -10,7 +10,7 @@ export class ClaimCertificateDTO {
     @ValidateNested()
     claimData?: ClaimDataDTO;
 
-    @ApiPropertyOptional({ type: String })
+    @ApiPropertyOptional({ type: String, example: '1000000'})
     @IsOptional()
     @Validate(PositiveBNStringValidator)
     @Validate(IntUnitsOfEnergy)

diff --git a/packages/traceability/issuer-api/src/pods/certificate/dto/claim-data.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/dto/claim-data.dto.ts
@@ -3,27 +3,27 @@ import { IClaimData } from '@energyweb/issuer';
 import { IsDateString, IsString } from 'class-validator';
 
 export class ClaimDataDTO implements IClaimData {
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "Beneficiary One" })
     @IsString()
     beneficiary: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "133 N. St, Orange County, CA 19444"})
     @IsString()
     location: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "US"})
     @IsString()
     countryCode: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "2021-11-08T17:11:11.883Z", description: "ISO String"})
     @IsDateString()
     periodStartDate: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "2021-11-08T17:11:11.883Z", description: "ISO String" })
     @IsDateString()
     periodEndDate: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "claiming" })
     @IsString()
     purpose: string;
 }
diff --git a/packages/traceability/issuer-api/src/pods/certificate/dto/claim.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/dto/claim.dto.ts
@@ -5,24 +5,24 @@ import { IntUnitsOfEnergy } from '@energyweb/origin-backend-utils';
 import { ClaimDataDTO } from './claim-data.dto';
 
 export class ClaimDTO implements IClaim {
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Certificate Id"})
     @IsInt()
     @IsPositive()
     id: number;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, description: "Public blockchain address", example: '0xd46aC0Bc23dB5e8AfDAAB9Ad35E9A3bA05E092E8' })
     @IsString()
     from: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, description: "Public blockchain address", example: '0xd46aC0Bc23dB5e8AfDAAB9Ad35E9A3bA05E092E8'})
     @IsString()
     to: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, description: "Represents topic of certificate", example: '2' })
     @IsString()
     topic: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "100000"})
     @Validate(IntUnitsOfEnergy)
     value: string;
 

diff --git a/packages/traceability/issuer-api/src/pods/certificate/dto/energy.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/dto/energy.dto.ts
@@ -3,15 +3,15 @@ import { ApiProperty } from '@nestjs/swagger';
 import { Validate } from 'class-validator';
 
 export class EnergyDTO {
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "5000"})
     @Validate(IntUnitsOfEnergy)
     publicVolume: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "5000"})
     @Validate(IntUnitsOfEnergy)
     privateVolume: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "5000"})
     @Validate(IntUnitsOfEnergy)
     claimedVolume: string;
 }
diff --git a/packages/traceability/issuer-api/src/pods/certificate/dto/issue-certificate.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/dto/issue-certificate.dto.ts
@@ -11,26 +11,26 @@ import {
 } from 'class-validator';
 
 export class IssueCertificateDTO {
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "'0xd46aC0Bc23dB5e8AfDAAB9Ad35E9A3bA05E092E9"})
     @IsEthereumAddress()
     to: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "900" })
     @Validate(PositiveBNStringValidator)
     @Validate(IntUnitsOfEnergy)
     energy: string;
 
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, example: 1636154471, description: "Unix Timestamp"})
     @IsInt()
     @IsPositive()
     fromTime: number;
 
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, example: 1636154476, description: "Unix Timestamp" })
     @IsInt()
     @IsPositive()
     toTime: number;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "B-145"})
     @IsString()
     deviceId: string;
 

diff --git a/packages/traceability/issuer-api/src/pods/certificate/dto/transfer-certificate.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/dto/transfer-certificate.dto.ts
@@ -4,7 +4,7 @@ import { IsOptional, IsString, Validate, ValidateNested } from 'class-validator'
 import { DelegatedTransferOptions } from '../utils/delegated-transfer.dto';
 
 export class TransferCertificateDTO {
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: '0xd46aC0Bc23dB5e8AfDAAB9Ad35E9A3bA05E092E8', description: "Public blockchain address"})
     @IsString()
     to: string;
 
@@ -13,7 +13,7 @@ export class TransferCertificateDTO {
     @ValidateNested()
     delegated?: DelegatedTransferOptions;
 
-    @ApiPropertyOptional({ type: String })
+    @ApiPropertyOptional({ type: String, example: "1000"})
     @IsOptional()
     @Validate(PositiveBNStringValidator)
     @Validate(IntUnitsOfEnergy)

diff --git a/packages/traceability/issuer-api/src/pods/certificate/dto/tx-hash.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/dto/tx-hash.dto.ts
@@ -2,6 +2,6 @@ import { ApiProperty } from '@nestjs/swagger';
 import { ContractTransaction } from 'ethers';
 
 export class TxHashDTO {
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "0x2b8da531e46cff1e217abc113495befac9384339feb10816b0f7f2ffa02fadd4"})
     txHash: ContractTransaction['hash'];
 }
diff --git a/packages/traceability/issuer-api/src/pods/certificate/utils/delegated-transfer.dto.ts b/packages/traceability/issuer-api/src/pods/certificate/utils/delegated-transfer.dto.ts
@@ -1,13 +1,13 @@
 import { ApiProperty } from '@nestjs/swagger';
-import { IsString, ValidateIf } from 'class-validator';
+import { IsString, ValidateIf, IsEthereumAddress } from 'class-validator';
 
 export class DelegatedTransferOptions {
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "0xf86c0a8502540be400825208944bbeeb066ed09b7aed07bf39eee0460dfa261520880de0b6b3a7640000801ca0f3ae52c1ef3300f44df0bcfd1341c232ed6134672b16e35699ae3f5fe2493379a023d23d2955a239dd6f61c4e8b2678d174356ff424eac53da53e17706c43ef871" })
     @IsString()
     signature: string;
 
-    @ApiProperty({ type: String, required: false })
+    @ApiProperty({ type: String, required: false, description: "Public blockchain address", example: '0xd46aC0Bc23dB5e8AfDAAB9Ad35E9A3bA05E092E8' })
     @ValidateIf((dto: DelegatedTransferOptions) => !!dto.from)
-    @IsString()
+    @IsEthereumAddress()
     from?: string;
 }
diff --git a/packages/traceability/issuer-api/src/pods/certification-request/certification-request.dto.ts b/packages/traceability/issuer-api/src/pods/certification-request/certification-request.dto.ts
@@ -13,39 +13,39 @@ import {
 } from 'class-validator';
 
 export class CertificationRequestDTO {
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Certificate Id" })
     @IsInt()
     @Min(0)
     id: number;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "DeviceB-789"})
     @IsString()
     deviceId: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "10000"})
     @Validate(PositiveBNStringValidator)
     @Validate(IntUnitsOfEnergy)
     energy: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, description: "Public blockchain address", example: '0xd46aC0Bc23dB5e8AfDAAB9Ad35E9A3bA05E092E8'})
     @IsString()
     owner: string;
 
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Unix timestamp", example: 1636154471})
     @IsInt()
     @IsPositive()
     fromTime: number;
 
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Unix timestamp", example: 1636154481})
     @IsInt()
     @IsPositive()
     toTime: number;
 
-    @ApiProperty({ type: [String] })
+    @ApiProperty({ type: [String], description: "Array of file names", example: ['test.pdf', 'test2.pdf']})
     @IsArray()
     files: string[];
 
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Unix timestamp", example: 1636154481})
     @IsInt()
     @IsPositive()
     created: number;
@@ -58,12 +58,12 @@ export class CertificationRequestDTO {
     @IsBoolean()
     revoked: boolean;
 
-    @ApiPropertyOptional({ type: Date })
+    @ApiPropertyOptional({ type: Date, example: "Sat Nov 06 2021 12:18:12 GMT-0400"  })
     @IsOptional()
     @IsDate()
     approvedDate?: Date;
 
-    @ApiPropertyOptional({ type: Date })
+    @ApiPropertyOptional({ type: Date, example: "Sat Nov 06 2021 12:18:12 GMT-0400" })
     @IsOptional()
     @IsDate()
     revokedDate?: Date;

diff --git a/...y/issuer-api/src/pods/certification-request/commands/approve-certification-request.dto.ts b/...y/issuer-api/src/pods/certification-request/commands/approve-certification-request.dto.ts
@@ -2,7 +2,7 @@ import { ApiProperty } from '@nestjs/swagger';
 import { IsInt, Min } from 'class-validator';
 
 export class ApproveCertificationRequestDTO {
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Certificate Id"})
     @IsInt()
     @Min(0)
     id: number;

diff --git a/...ty/issuer-api/src/pods/certification-request/commands/create-certification-request.dto.ts b/...ty/issuer-api/src/pods/certification-request/commands/create-certification-request.dto.ts
@@ -12,31 +12,31 @@ import {
 } from 'class-validator';
 
 export class CreateCertificationRequestDTO {
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, description: "Public blockchain address", example: '0xd46aC0Bc23dB5e8AfDAAB9Ad35E9A3bA05E092E8'})
     @IsString()
     @IsNotEmpty()
     to: string;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: '1000000'})
     @Validate(PositiveBNStringValidator)
     @Validate(IntUnitsOfEnergy)
     energy: string;
 
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Unix timestamp", example: 1636154471})
     @IsInt()
     @IsPositive()
     fromTime: number;
 
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Unix timestamp", example: 1636154471})
     @IsInt()
     @IsPositive()
     toTime: number;
 
-    @ApiProperty({ type: String })
+    @ApiProperty({ type: String, example: "DeviceB-789" })
     @IsString()
     deviceId: string;
 
-    @ApiProperty({ type: [String], required: false })
+    @ApiProperty({ type: [String], required: false, example: ['test.pdf', 'test2.pdf']})
     @ValidateIf((dto: CreateCertificationRequestDTO) => !!dto.files)
     @IsArray()
     files?: string[];

diff --git a/...ty/issuer-api/src/pods/certification-request/commands/revoke-certification-request.dto.ts b/...ty/issuer-api/src/pods/certification-request/commands/revoke-certification-request.dto.ts
@@ -2,7 +2,7 @@ import { ApiProperty } from '@nestjs/swagger';
 import { IsInt, Min } from 'class-validator';
 
 export class RevokeCertificationRequestDTO {
-    @ApiProperty({ type: Number })
+    @ApiProperty({ type: Number, description: "Certificate Request Id" })
     @IsInt()
     @Min(0)
     id: number;