From e5e2d6fc2dc3606f1969c7f34c67c6d1a9444bfb Mon Sep 17 00:00:00 2001
From: Jose Andres Tejerina <andres.tejerina@exomindset.co>
Date: Thu, 16 Oct 2025 15:57:14 -0300
Subject: [PATCH] feat: Add openapi documentation for
 OAuth2SummitNotificationsApiController

---
 ...OAuth2SummitNotificationsApiController.php | 119 +++++++++++++++++-
 app/Swagger/SummitPushNotificationSchemas.php |  85 +++++++++++++
 2 files changed, 203 insertions(+), 1 deletion(-)
 create mode 100644 app/Swagger/SummitPushNotificationSchemas.php

diff --git a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitNotificationsApiController.php b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitNotificationsApiController.php
index 207c0abc0..b462e6f7c 100644
--- a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitNotificationsApiController.php
+++ b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitNotificationsApiController.php
@@ -28,6 +28,9 @@
 use Illuminate\Support\Facades\Validator;
 use Illuminate\Support\Facades\Request;
 use Exception;
+use OpenApi\Attributes as OA;
+use Symfony\Component\HttpFoundation\Response;
+
 /**
  * Class OAuth2SummitNotificationsApiController
  * @package App\Http\Controllers
@@ -81,6 +84,63 @@ public function __construct
      * @param $summit_id
      * @return mixed
      */
+    #[OA\Get(
+        path: '/api/v1/summits/{id}/notifications',
+        operationId: 'getNotifications',
+        description: 'Get all push notifications for a summit',
+        parameters: [
+            new OA\Parameter(
+                name: 'id',
+                description: 'Summit ID',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'integer')
+            ),
+            new OA\Parameter(
+                name: 'page',
+                description: 'Page number',
+                in: 'query',
+                schema: new OA\Schema(type: 'integer', default: 1)
+            ),
+            new OA\Parameter(
+                name: 'per_page',
+                description: 'Items per page',
+                in: 'query',
+                schema: new OA\Schema(type: 'integer', default: 10)
+            ),
+            new OA\Parameter(
+                name: 'expand',
+                description: 'Expand relations (event,group,recipients)',
+                in: 'query',
+                schema: new OA\Schema(type: 'string')
+            ),
+        ],
+        tags: ['Summit Notifications'],
+        security: [['oauth2' => ['summit-read']]],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: 'List of notifications',
+                content: new OA\JsonContent(
+                    properties: [
+                        new OA\Property(
+                            property: 'data',
+                            type: 'array',
+                            items: new OA\Items(ref: '#/components/schemas/SummitPushNotificationResponse')
+                        ),
+                        new OA\Property(property: 'total', type: 'integer'),
+                        new OA\Property(property: 'per_page', type: 'integer'),
+                        new OA\Property(property: 'current_page', type: 'integer'),
+                        new OA\Property(property: 'last_page', type: 'integer'),
+                    ]
+                )
+            ),
+            new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: 'Unauthorized'),
+            new OA\Response(response: Response::HTTP_FORBIDDEN, description: 'Forbidden'),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: 'Summit not found'),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: 'Server Error'),
+        ]
+    )]
     public function getAll($summit_id)
     {
         $summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
@@ -142,8 +202,65 @@ function ($page,  $per_page,  $filter,  $order, $applyExtraFilters) use ($summit
 
     /**
      * @param $summit_id
-     * @return \Illuminate\Http\JsonResponse|mixed
+     * @return mixed
      */
+    #[OA\Get(
+        path: '/api/v1/summits/{id}/notifications/sent',
+        operationId: 'getApprovedNotifications',
+        description: 'Get all approved push notifications sent to current user',
+        parameters: [
+            new OA\Parameter(
+                name: 'id',
+                description: 'Summit ID',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'integer')
+            ),
+            new OA\Parameter(
+                name: 'page',
+                description: 'Page number',
+                in: 'query',
+                schema: new OA\Schema(type: 'integer', default: 1)
+            ),
+            new OA\Parameter(
+                name: 'per_page',
+                description: 'Items per page',
+                in: 'query',
+                schema: new OA\Schema(type: 'integer', default: 10)
+            ),
+            new OA\Parameter(
+                name: 'expand',
+                description: 'Expand relations (event,group,recipients)',
+                in: 'query',
+                schema: new OA\Schema(type: 'string')
+            ),
+        ],
+        tags: ['Summit Notifications'],
+        security: [['oauth2' => ['summit-read']]],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: 'List of approved notifications',
+                content: new OA\JsonContent(
+                    properties: [
+                        new OA\Property(
+                            property: 'data',
+                            type: 'array',
+                            items: new OA\Items(ref: '#/components/schemas/SummitPushNotificationResponse')
+                        ),
+                        new OA\Property(property: 'total', type: 'integer'),
+                        new OA\Property(property: 'per_page', type: 'integer'),
+                        new OA\Property(property: 'current_page', type: 'integer'),
+                        new OA\Property(property: 'last_page', type: 'integer'),
+                    ]
+                )
+            ),
+            new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: 'Unauthorized'),
+            new OA\Response(response: Response::HTTP_FORBIDDEN, description: 'Forbidden'),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: 'Summit not found'),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: 'Server Error'),
+        ]
+    )]
     public function getAllApprovedByUser($summit_id){
 
         $summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->resource_server_context)->find($summit_id);
diff --git a/app/Swagger/SummitPushNotificationSchemas.php b/app/Swagger/SummitPushNotificationSchemas.php
new file mode 100644
index 000000000..4d7a8f310
--- /dev/null
+++ b/app/Swagger/SummitPushNotificationSchemas.php
@@ -0,0 +1,85 @@
+<?php
+
+namespace App\Swagger\Summit;
+
+use OpenApi\Attributes as OA;
+
+class SummitPushNotification
+{
+    #[OA\Schema(
+        schema: 'SummitPushNotificationRequest',
+        type: 'object',
+        required: ['title', 'body', 'channel'],
+        properties: [
+            new OA\Property(property: 'title', type: 'string', description: 'Notification title'),
+            new OA\Property(property: 'body', type: 'string', description: 'Notification body'),
+            new OA\Property(property: 'channel', type: 'string', enum: ['Event', 'Group', 'Members'], description: 'Channel type'),
+            new OA\Property(property: 'event_id', type: 'integer', description: 'Event ID (required if channel is Event)'),
+            new OA\Property(property: 'group_id', type: 'integer', description: 'Group ID (required if channel is Group)'),
+            new OA\Property(property: 'recipients', type: 'array', items: new OA\Items(type: 'integer'), description: 'Array of member IDs (required if channel is Members)'),
+            new OA\Property(property: 'approved', type: 'boolean', description: 'Is notification approved'),
+        ]
+    )]
+    public function __construct() {}
+}
+
+class SummitPushNotificationResponse
+{
+    #[OA\Schema(
+        schema: 'SummitPushNotificationResponse',
+        type: 'object',
+        properties: [
+            new OA\Property(property: 'id', type: 'integer'),
+            new OA\Property(property: 'title', type: 'string'),
+            new OA\Property(property: 'body', type: 'string'),
+            new OA\Property(property: 'channel', type: 'string', enum: ['Event', 'Group', 'Members']),
+            new OA\Property(property: 'summit_id', type: 'integer'),
+            new OA\Property(property: 'event_id', type: 'integer', nullable: true),
+            new OA\Property(property: 'group_id', type: 'integer', nullable: true),
+            new OA\Property(property: 'recipients', type: 'array', items: new OA\Items(type: 'integer')),
+            new OA\Property(property: 'approved', type: 'boolean'),
+            new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
+            new OA\Property(property: 'updated_at', type: 'string', format: 'date-time'),
+        ]
+    )]
+    public function __construct() {}
+}
+
+class SummitPushNotificationResponseExpanded
+{
+    #[OA\Schema(
+        schema: 'SummitPushNotificationResponseExpanded',
+        type: 'object',
+        properties: [
+            new OA\Property(property: 'id', type: 'integer'),
+            new OA\Property(property: 'title', type: 'string'),
+            new OA\Property(property: 'body', type: 'string'),
+            new OA\Property(property: 'channel', type: 'string', enum: ['Event', 'Group', 'Members']),
+            new OA\Property(property: 'summit_id', type: 'integer'),
+            new OA\Property(
+                property: 'event_id',
+                type: 'array',
+                items: new OA\Items(type: ['integer', 'SummitEventResponse']),
+                nullable: true,
+                description: 'Event ID or expanded event object'
+            ),
+            new OA\Property(
+                property: 'group_id',
+                type: 'array',
+                items: new OA\Items(type: ['integer', 'ChatTeamResponse']),
+                nullable: true,
+                description: 'Group ID or expanded group object'
+            ),
+            new OA\Property(
+                property: 'recipients',
+                type: 'array',
+                items: new OA\Items(type: ['integer', 'PublicMemberResponse']),
+                description: 'Array of member IDs or expanded member objects'
+            ),
+            new OA\Property(property: 'approved', type: 'boolean'),
+            new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
+            new OA\Property(property: 'updated_at', type: 'string', format: 'date-time'),
+        ]
+    )]
+    public function __construct() {}
+}
\ No newline at end of file