docs: update swagger examples for external endpoints

Signed-off-by: kirill-tolochko <kirill.tolochko.work@gmail.com>

Author: kirill-tolochko

api-gateway/src/api/service/external.ts

@@ -1,8 +1,8 @@
 import { InternalException, PolicyEngine } from '#helpers';
-import { Examples, ExternalDocumentDTO, InternalServerErrorDTO, ResponseDTOWithSyncEvents } from '#middlewares';
+import { Examples, ExternalDocumentDTO, InternalServerErrorDTO, ObjectExamples, ResponseDTOWithSyncEvents } from '#middlewares';
 import { PinoLogger } from '@guardian/common';
 import { Body, Controller, DefaultValuePipe, HttpCode, HttpStatus, Param, ParseBoolPipe, Post, Query } from '@nestjs/common';
-import { ApiBody, ApiExtraModels, ApiInternalServerErrorResponse, ApiOkResponse, ApiOperation, ApiParam, ApiQuery, ApiTags } from '@nestjs/swagger';
+import { ApiBody, ApiInternalServerErrorResponse, ApiOkResponse, ApiOperation, ApiParam, ApiQuery, ApiTags } from '@nestjs/swagger';
 
 @Controller('external')
 @ApiTags('external')
@@ -20,7 +20,12 @@ export class ExternalApi {
     })
     @ApiBody({
         description: 'Object that contains a VC Document.',
-        type: ExternalDocumentDTO
+        type: ExternalDocumentDTO,
+        examples: {
+            'Request Body': {
+                value: ObjectExamples.EXTERNAL_REQUEST_BODY_EXAMPLE
+            }
+        }
     })
     @ApiParam({
         name: 'policyId',
@@ -46,7 +51,6 @@ export class ExternalApi {
         type: InternalServerErrorDTO,
         example: { code: 500, message: 'Error message' }
     })
-    @ApiExtraModels(ExternalDocumentDTO, InternalServerErrorDTO)
     @HttpCode(HttpStatus.OK)
     async receiveExternalDataCustom(
         @Param('policyId') policyId: string,
@@ -71,7 +75,12 @@ export class ExternalApi {
     })
     @ApiBody({
         description: 'Object that contains a VC Document.',
-        type: ExternalDocumentDTO
+        type: ExternalDocumentDTO,
+        examples: {
+            'Request Body': {
+                value: ObjectExamples.EXTERNAL_REQUEST_BODY_EXAMPLE
+            }
+        }
     })
     @ApiOkResponse({
         description: 'Successful operation.',
@@ -83,7 +92,6 @@ export class ExternalApi {
         type: InternalServerErrorDTO,
         example: { code: 500, message: 'Error message' }
     })
-    @ApiExtraModels(ExternalDocumentDTO, InternalServerErrorDTO)
     @HttpCode(HttpStatus.OK)
     async receiveExternalData(
         @Body() document: ExternalDocumentDTO
@@ -106,7 +114,12 @@ export class ExternalApi {
     })
     @ApiBody({
         description: 'Object that contains a VC Document.',
-        type: ExternalDocumentDTO
+        type: ExternalDocumentDTO,
+        examples: {
+            'Request Body': {
+                value: ObjectExamples.EXTERNAL_REQUEST_BODY_EXAMPLE
+            }
+        }
     })
     @ApiQuery({
         name: 'history',
@@ -132,14 +145,13 @@ export class ExternalApi {
     @ApiOkResponse({
         description: 'Successful operation.',
         type: ResponseDTOWithSyncEvents,
-        example: { result: 'ok' }
+        example: ObjectExamples.EXTERNAL_SYNC_EVENTS_RESPONSE_EXAMPLE
     })
     @ApiInternalServerErrorResponse({
         description: 'Internal server error.',
         type: InternalServerErrorDTO,
         example: { code: 500, message: 'Error message' }
     })
-    @ApiExtraModels(ExternalDocumentDTO, ResponseDTOWithSyncEvents, InternalServerErrorDTO)
     @HttpCode(HttpStatus.OK)
     async receiveExternalDataCustomWithSyncEvents(
         @Param('policyId') policyId: string,
@@ -165,7 +177,12 @@ export class ExternalApi {
     })
     @ApiBody({
         description: 'Object that contains a VC Document.',
-        type: ExternalDocumentDTO
+        type: ExternalDocumentDTO,
+        examples: {
+            'Request Body': {
+                value: ObjectExamples.EXTERNAL_REQUEST_BODY_EXAMPLE
+            }
+        }
     })
     @ApiQuery({
         name: 'history',
@@ -177,14 +194,13 @@ export class ExternalApi {
     @ApiOkResponse({
         description: 'Successful operation.',
         type: ResponseDTOWithSyncEvents,
-        example: { result: 'ok' }
+        example: ObjectExamples.EXTERNAL_SYNC_EVENTS_RESPONSE_EXAMPLE
     })
     @ApiInternalServerErrorResponse({
         description: 'Internal server error.',
         type: InternalServerErrorDTO,
         example: { code: 500, message: 'Error message' }
     })
-    @ApiExtraModels(ExternalDocumentDTO, ResponseDTOWithSyncEvents, InternalServerErrorDTO)
     @HttpCode(HttpStatus.OK)
     async receiveExternalDataWithSyncEvents(
         @Query('history', new DefaultValuePipe(false), ParseBoolPipe) history: boolean,

api-gateway/src/middlewares/validation/examples.ts

@@ -21,6 +21,45 @@ export enum Examples {
     USER_NAME_SR_2 = 'Verra'
 }
 
+const EXTERNAL_REQUEST_BODY_EXAMPLE = {
+    owner: 'string',
+    policyTag: 'string',
+    document: {
+        id: '8f457a5a-c02b-4a18-a7d3-20e4def1bf7f',
+        '@context': [
+            'https://www.w3.org/2018/credentials/v1'
+        ],
+        type: [
+            'VerifiableCredential',
+            'a2274869-4a41-4446-8efd-dacde5a81221'
+        ],
+        credentialSubject: [
+            {
+                id: 'did:hedera:testnet:4YZuEXk95TMt2WfuAB5UYJMQSgSfUgBNutnZioUVAxkR_0.0.1774462341919',
+                field0: 'value0',
+                field1: 'value1',
+                policyId: '69c42569ae73da728c8d9027',
+                accountId: '0.0.1774462367074'
+            }
+        ],
+        issuer: 'did:hedera:testnet:4YZuEXk95TMt2WfuAB5UYJMQSgSfUgBNutnZioUVAxkR_0.0.1774462341919',
+        issuanceDate: '2026-03-25T17:12:17.150Z',
+        proof: {
+            type: 'Ed25519Signature2018',
+            created: '2026-03-25T17:12:17.150Z',
+            verificationMethod: 'did:hedera:testnet:4YZuEXk95TMt2WfuAB5UYJMQSgSfUgBNutnZioUVAxkR_0.0.1774462341919#did-root-key',
+            proofPurpose: 'assertionMethod',
+            jws: 'eyJhbGciOiJFZERTQSJ9..signature'
+        }
+    }
+};
+
+const EXTERNAL_SYNC_EVENTS_RESPONSE_EXAMPLE = {
+    response: {},
+    result: null,
+    steps: []
+};
+
 const PERMISSIONS_SR = [
     'ACCOUNTS_STANDARD_REGISTRY_READ',
     'DEMO_KEY_CREATE',
@@ -169,6 +208,8 @@ const PROFILE_DID_DOCUMENT_SAMPLE = {
 
 export const ObjectExamples = {
     PERMISSION_SR: PERMISSIONS_SR,
+    EXTERNAL_REQUEST_BODY_EXAMPLE: EXTERNAL_REQUEST_BODY_EXAMPLE,
+    EXTERNAL_SYNC_EVENTS_RESPONSE_EXAMPLE: EXTERNAL_SYNC_EVENTS_RESPONSE_EXAMPLE,
 
     CONTRACTS_LIST_RESPONSE_WIPE: [
         {