Feature | Extend Swagger Coverage for controller PaymentGatewayWebHookController

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,44 @@ 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: ["Payment Gateway Webhook"],
+        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"
+            ),
+            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 +192,51 @@ public function genericConfirm($application_type, LaravelRequest $request){
      * @param LaravelRequest $request
      * @return \Illuminate\Http\JsonResponse|mixed
      */
+    #[OA\Post(
+        path: "/api/public/v1/summits/{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: "summitConfirm",
+        tags: ["Payment Gateway Webhook"],
+        parameters: [
+            new OA\Parameter(
+                name: "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"
+            ),
+            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/Repositories/Summit/DoctrineSummitAttendeeTicketRepository.php

@@ -52,26 +52,26 @@ public function __construct(EntityManagerInterface $em, ClassMetadata $class)
 
     /** @var array<string, array{0:string,1:'join'|'leftJoin',2:array<int,string>}> */
     private array $joinCatalog = [
-        'o' => ['e.order', 'join', []],
-        's' => ['e.summit', 'join', []],
-        'ord_m' => ['o.owner', 'leftJoin', ['o']],
-        'a' => ['e.owner', 'leftJoin', []],
-        'a_c' => ['a.company', 'leftJoin', ['a']],
-        'm' => ['a.member', 'leftJoin', ['a']],
-        'am' => ['a.manager', 'leftJoin', ['a']],
-        'm2' => ['am.member', 'leftJoin', ['am']],
-        'b' => ['e.badge', 'leftJoin', []],
-        'bt' => ['b.type', 'leftJoin', ['b']],
-        'al' => ['bt.access_levels', 'leftJoin', ['bt']],
-        'bf' => ['b.features', 'leftJoin', ['b']],
-        'bt_bf' => ['bt.badge_features', 'leftJoin', ['bt']],
-        'prt' => ['b.prints', 'leftJoin', ['b']],
-        'rr' => ['e.refund_requests', 'leftJoin', []],
-        'ta' => ['e.applied_taxes', 'leftJoin', []],
-        'tt' => ['e.ticket_type', 'join', []],
-        'pc' => ['e.promo_code', 'leftJoin', []],
-        'pct' => ['pc.tags', 'leftJoin', ['pc']],
-        'avt' => ['bt.allowed_view_types', 'join', ['bt']],
+        'o'      => ['e.order',               'join',     []],
+        's'      => ['e.summit',              'join',     []],
+        'ord_m'  => ['o.owner',               'leftJoin', ['o']],
+        'a'      => ['e.owner',               'leftJoin', []],
+        'a_c'    => ['a.company',             'leftJoin', ['a']],
+        'm'      => ['a.member',              'leftJoin', ['a']],
+        'am'     => ['a.manager',             'leftJoin', ['a']],
+        'm2'     => ['am.member',             'leftJoin', ['am']],
+        'b'      => ['e.badge',               'leftJoin', []],
+        'bt'     => ['b.type',                'leftJoin', ['b']],
+        'al'     => ['bt.access_levels',      'leftJoin', ['bt']],
+        'bf'     => ['b.features',            'leftJoin', ['b']],
+        'bt_bf'  => ['bt.badge_features',     'leftJoin', ['bt']],
+        'prt'    => ['b.prints',              'leftJoin', ['b']],
+        'rr'     => ['e.refund_requests',     'leftJoin', []],
+        'ta'     => ['e.applied_taxes',       'leftJoin', []],
+        'tt'     => ['e.ticket_type',         'join',     []],
+        'pc'     => ['e.promo_code',          'leftJoin', []],
+        'pct'    => ['pc.tags',               'leftJoin', ['pc']],
+        'avt'    => ['bt.allowed_view_types', 'join',     ['bt']],
     ];
 
     private function ensureJoin(QueryBuilder $qb, string $alias): void

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 {}