feat: Extend Swagger Coverage for controller PaymentGatewayWebHookController

Author: andrestejerina97

app/Http/Controllers/PaymentGatewayWebHookController.php

@@ -16,6 +16,8 @@
 use App\Services\Model\IProcessPaymentService;
 use App\Services\Model\ISummitOrderService;
 use Illuminate\Http\Request as LaravelRequest;
+use Illuminate\Http\Response;
+use Illuminate\Support\Facades\Cache;
 use models\oauth2\IResourceServerContext;
 use models\summit\IPaymentConstants;
 use models\summit\ISummitRepository;
@@ -24,6 +26,8 @@
 use models\exceptions\EntityNotFoundException;
 use models\exceptions\ValidationException;
 use Exception;
+use OpenApi\Attributes as OA;
+
 /**
  * Class PaymentGatewayWebHookController
  * @package App\Http\Controllers
@@ -96,6 +100,46 @@ private function getProcessPaymentService(string $application_type):?IProcessPay
      * @param LaravelRequest $request
      * @return \Illuminate\Http\JsonResponse|mixed
      */
+    #[OA\Post(
+        path: "/api/public/v1/summits/all/payments/{application_name}/confirm",
+        summary: "Generic payment gateway webhook confirmation",
+        description: "Handles payment gateway webhook callbacks for a given application type.",
+        operationId: "genericConfirm",
+        tags: ["PaymentGatewayHook"],
+        security: [],
+        parameters: [
+            new OA\Parameter(
+                name: "application_name",
+                in: "path",
+                required: true,
+                description: "Application name (e.g. Show admin)",
+                schema: new OA\Schema(type: "string")
+            )
+        ],
+        requestBody: new OA\RequestBody(
+            required: false,
+            content: new OA\JsonContent(ref: '#/components/schemas/PaymentGatewayWebhookRequest')
+        ),
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Payment processed successfully",
+                content: new OA\JsonContent(ref: '#/components/schemas/PaymentProcessingResponse')
+            ),
+            new OA\Response(
+                response: Response::HTTP_ALREADY_REPORTED,
+                description: "Already reported"
+            ),
+            new OA\Response(
+                response: Response::HTTP_BAD_REQUEST,
+                description: "Payload error"
+            ),
+            new OA\Response(
+                response: Response::HTTP_PRECONDITION_FAILED,
+                description: "Precondition failed - missing configuration or invalid data"
+            )
+        ]
+    )]
     public function genericConfirm($application_type, LaravelRequest $request){
         try {
 
@@ -150,6 +194,53 @@ public function genericConfirm($application_type, LaravelRequest $request){
      * @param LaravelRequest $request
      * @return \Illuminate\Http\JsonResponse|mixed
      */
+    #[OA\Post(
+        path: "/api/public/v1/summits/{summit_id}/payments/{application_name}/confirm",
+        summary: "Summit payment gateway webhook confirmation",
+        description: "Handles payment gateway webhook callbacks for a given summit and application type.",
+        operationId: "confirm",
+        tags: ["PaymentGatewayHook"],
+        security: [],
+        parameters: [
+            new OA\Parameter(
+                name: "summit_id",
+                in: "path",
+                required: true,
+                description: "Summit identifier",
+                schema: new OA\Schema(type: "integer")
+            ),
+            new OA\Parameter(
+                name: "application_name",
+                in: "path",
+                required: true,
+                description: "Application Name (e.g ShowAdmin)",
+                schema: new OA\Schema(type: "string")
+            )
+        ],
+        requestBody: new OA\RequestBody(
+            required: false,
+            content: new OA\JsonContent(ref: '#/components/schemas/PaymentGatewayWebhookRequest')
+        ),
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Payment processed successfully",
+                content: new OA\JsonContent(ref: '#/components/schemas/PaymentProcessingResponse')
+            ),
+            new OA\Response(
+                response: Response::HTTP_ALREADY_REPORTED,
+                description: "Already reported"
+            ),
+            new OA\Response(
+                response: Response::HTTP_BAD_REQUEST,
+                description: "Payload error"
+            ),
+            new OA\Response(
+                response: Response::HTTP_PRECONDITION_FAILED,
+                description: "Precondition failed - missing configuration or invalid data"
+            )
+        ]
+    )]
     public function confirm($summit_id, $application_type, LaravelRequest $request){
 
         try {

app/Swagger/PaymentGatewayWebhookSchemas.php

@@ -0,0 +1,44 @@
+<?php 
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'PaymentGatewayWebhookRequest',
+    type: 'object',
+    description: 'Generic payment gateway webhook payload. The structure depends on the payment provider (e.g., Stripe, etc.)',
+    properties: [
+        new OA\Property(
+            property: 'id',
+            type: 'string',
+            example: 'evt_1234567890',
+            description: 'Webhook event ID from payment provider'
+        ),
+        new OA\Property(
+            property: 'type',
+            type: 'string',
+            example: 'charge.succeeded',
+            description: 'Event type from payment provider'
+        ),
+        new OA\Property(
+            property: 'cart_id',
+            type: 'string',
+            example: '1234567890',
+            description: 'Cart or order identifier'
+        ),
+        new OA\Property(
+            property: 'data',
+            type: 'object',
+            description: 'Event data payload from payment provider'
+        ),
+    ]
+)]
+class PaymentGatewayWebhookRequestSchema {}
+
+#[OA\Schema(
+    schema: 'PaymentProcessingResponse',
+    type: 'string',
+    example: 'ok',
+    description: 'Confirmation message that payment was processed successfully'
+)]
+class PaymentProcessingResponseSchema {}