From 49a3bef2c497cf17232b644bfe34be518b353be9 Mon Sep 17 00:00:00 2001
From: Jose Andres Tejerina <andres.tejerina@exomindset.co>
Date: Thu, 13 Nov 2025 17:07:54 -0300
Subject: [PATCH 1/2] feat: Add openapi documentation for
 OAuth2SummitSubmittersApiController

---
 .../OAuth2SummitSubmittersApiController.php   | 189 ++++++++++++++++--
 app/Swagger/SubmitterSchemas.php              |  90 +++++++++
 .../security/SummitSubmittersOAuthSchema.php  |  30 +++
 3 files changed, 297 insertions(+), 12 deletions(-)
 create mode 100644 app/Swagger/SubmitterSchemas.php
 create mode 100644 app/Swagger/security/SummitSubmittersOAuthSchema.php

diff --git a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmittersApiController.php b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmittersApiController.php
index b42f25c32..d48fcc944 100644
--- a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmittersApiController.php
+++ b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmittersApiController.php
@@ -13,6 +13,8 @@
  **/
 
 use App\ModelSerializers\IMemberSerializerTypes;
+use App\Models\Foundation\Main\IGroup;
+use App\Security\SummitScopes;
 use Illuminate\Support\Facades\Request;
 use models\main\IMemberRepository;
 use models\oauth2\IResourceServerContext;
@@ -21,6 +23,8 @@
 use utils\Filter;
 use utils\FilterParser;
 use utils\PagingInfo;
+use OpenApi\Attributes as OA;
+use Symfony\Component\HttpFoundation\Response;
 
 /**
  * Class OAuth2SummitSubmittersApiController
@@ -66,10 +70,72 @@ public function __construct
         $this->service = $service;
     }
 
-    /**
-     * @param $summit_id
-     * @return \Illuminate\Http\JsonResponse|mixed
-     */
+    #[OA\Get(
+        path: "/api/v1/summits/{id}/submitters",
+        summary: "Get all submitters for a summit",
+        operationId: "getSubmittersBySummit",
+        tags: ["SummitSubmitters"],
+        security: [['summit_submitters_oauth2' => [
+            SummitScopes::ReadSummitData,
+            SummitScopes::ReadAllSummitData,
+        ]]],
+        parameters: [
+            new OA\Parameter(
+                name: "id",
+                in: "path",
+                required: true,
+                description: "Summit ID or slug",
+                schema: new OA\Schema(type: "string")
+            ),
+            new OA\Parameter(
+                name: "page",
+                in: "query",
+                required: false,
+                description: "Page number",
+                schema: new OA\Schema(type: "integer", default: 1)
+            ),
+            new OA\Parameter(
+                name: "per_page",
+                in: "query",
+                required: false,
+                description: "Items per page",
+                schema: new OA\Schema(type: "integer", default: 10)
+            ),
+            new OA\Parameter(
+                name: "filter",
+                in: "query",
+                required: false,
+                description: "Filter query (supports multiple operators)",
+                schema: new OA\Schema(type: "string", example: "first_name=@John")
+            ),
+            new OA\Parameter(
+                name: "order",
+                in: "query",
+                required: false,
+                description: "Order by field (prefix with - for descending)",
+                schema: new OA\Schema(type: "string", example: "first_name,-created")
+            ),
+            new OA\Parameter(
+                name: "expand",
+                in: "query",
+                required: false,
+                description: "Expand relations (presentations, member)",
+                schema: new OA\Schema(type: "string", example: "presentations,member")
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Successful response with paginated submitters",
+                content: new OA\JsonContent(ref: '#/components/schemas/PaginatedSubmittersResponse')
+            ),
+            new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
+            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 getAllBySummit($summit_id)
     {
         $summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find(intval($summit_id));
@@ -158,10 +224,62 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use ($summit) {
         );
     }
 
-    /**
-     * @param $summit_id
-     * @return \Illuminate\Http\JsonResponse|mixed
-     */
+    #[OA\Get(
+        path: "/api/v1/summits/{id}/submitters/csv",
+        description: "required-groups " . IGroup::SummitAdministrators . ", " . IGroup::SuperAdmins . ", " . IGroup::Administrators,
+        summary: "Get all submitters for a summit in CSV format",
+        operationId: "getSubmittersCSV",
+        tags: ["SummitSubmitters"],
+        security: [['summit_submitters_oauth2' => [
+            SummitScopes::ReadSummitData,
+            SummitScopes::ReadAllSummitData,
+        ]]],
+        x: [
+            'required-groups' => [
+                IGroup::SummitAdministrators,
+                IGroup::SuperAdmins,
+                IGroup::Administrators,
+            ]
+        ],
+        parameters: [
+            new OA\Parameter(
+                name: "id",
+                in: "path",
+                required: true,
+                description: "Summit ID or slug",
+                schema: new OA\Schema(type: "string")
+            ),
+            new OA\Parameter(
+                name: "filter",
+                in: "query",
+                required: false,
+                description: "Filter query to select specific submitters",
+                schema: new OA\Schema(type: "string", example: "first_name=@John")
+            ),
+            new OA\Parameter(
+                name: "order",
+                in: "query",
+                required: false,
+                description: "Order by field (prefix with - for descending)",
+                schema: new OA\Schema(type: "string", example: "first_name,-created")
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "CSV file with submitter data",
+                content: new OA\MediaType(
+                    mediaType: "text/csv",
+                    schema: new OA\Schema(type: "string", format: "binary")
+                )
+            ),
+            new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
+            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 getAllBySummitCSV($summit_id)
     {
         $summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find(intval($summit_id));
@@ -255,10 +373,57 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use ($summit) {
         );
     }
 
-    /**
-     * @param $summit_id
-     * @return \Illuminate\Http\JsonResponse|mixed
-     */
+    #[OA\Put(
+        path: "/api/v1/summits/{id}/submitters/all/send",
+        description: "required-groups " . IGroup::SummitAdministrators . ", " . IGroup::SuperAdmins . ", " . IGroup::Administrators . ", " . IGroup::SummitRegistrationAdmins,
+        summary: "Send bulk emails to submitters",
+        operationId: "sendSubmittersBulkEmails",
+        tags: ["SummitSubmitters"],
+        security: [['summit_submitters_oauth2' => [
+            SummitScopes::WriteSummitData,
+            SummitScopes::WriteSpeakersData,
+        ]]],
+        x: [
+            'required-groups' => [
+                IGroup::SummitAdministrators,
+                IGroup::SuperAdmins,
+                IGroup::Administrators,
+                IGroup::SummitRegistrationAdmins,
+            ]
+        ],
+        parameters: [
+            new OA\Parameter(
+                name: "id",
+                in: "path",
+                required: true,
+                description: "Summit ID or slug",
+                schema: new OA\Schema(type: "string")
+            ),
+            new OA\Parameter(
+                name: "filter",
+                in: "query",
+                required: false,
+                description: "Filter query to select specific submitters",
+                schema: new OA\Schema(type: "string", example: "has_accepted_presentations==true")
+            ),
+        ],
+        requestBody: new OA\RequestBody(
+            required: true,
+            content: new OA\JsonContent(ref: "#/components/schemas/SendSubmittersEmailsRequest")
+        ),
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "Emails sent successfully"
+            ),
+            new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
+            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_PRECONDITION_FAILED, description: "Validation Error"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
     public function send($summit_id)
     {
         return $this->processRequest(function () use ($summit_id) {
diff --git a/app/Swagger/SubmitterSchemas.php b/app/Swagger/SubmitterSchemas.php
new file mode 100644
index 000000000..0920a03be
--- /dev/null
+++ b/app/Swagger/SubmitterSchemas.php
@@ -0,0 +1,90 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'Submitter',
+    type: 'object',
+    description: 'Submitter extends Member with presentation data',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/Member'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: 'accepted_presentations',
+                    type: 'array',
+                    items: new OA\Items(type: 'integer'),
+                    description: 'Array of accepted presentation IDs. Use expand=accepted_presentations to get full objects'
+                ),
+                new OA\Property(
+                    property: 'alternate_presentations',
+                    type: 'array',
+                    items: new OA\Items(type: 'integer'),
+                    description: 'Array of alternate presentation IDs. Use expand=alternate_presentations to get full objects'
+                ),
+                new OA\Property(
+                    property: 'rejected_presentations',
+                    type: 'array',
+                    items: new OA\Items(type: 'integer'),
+                    description: 'Array of rejected presentation IDs. Use expand=rejected_presentations to get full objects'
+                ),
+            ]
+        )
+    ]
+)]
+class SubmitterSchemas {}
+
+/**
+ * Paginated Submitters Response
+ */
+#[OA\Schema(
+    schema: 'PaginatedSubmittersResponse',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: 'data',
+                    type: 'array',
+                    description: 'List of submitters',
+                    items: new OA\Items(ref: '#/components/schemas/Submitter')
+                )
+            ]
+        )
+    ]
+)]
+class PaginatedSubmittersResponseSchema {}
+
+/**
+ * Send Emails to Submitters Request
+ */
+#[OA\Schema(
+    schema: 'SendSubmittersEmailsRequest',
+    type: 'object',
+    required: ['subject', 'body'],
+    properties: [
+        new OA\Property(
+            property: 'subject',
+            type: 'string',
+            example: 'Important Update for Submitters',
+            description: 'Email subject'
+        ),
+        new OA\Property(
+            property: 'body',
+            type: 'string',
+            example: 'Dear Submitter, here is an important update...',
+            description: 'Email body content'
+        ),
+        new OA\Property(
+            property: 'filter',
+            type: 'string',
+            example: 'has_accepted_presentations==true',
+            description: 'Optional filter to select specific submitters'
+        ),
+    ]
+)]
+class SendSubmittersEmailsRequestSchema {}
\ No newline at end of file
diff --git a/app/Swagger/security/SummitSubmittersOAuthSchema.php b/app/Swagger/security/SummitSubmittersOAuthSchema.php
new file mode 100644
index 000000000..a496b76f2
--- /dev/null
+++ b/app/Swagger/security/SummitSubmittersOAuthSchema.php
@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use App\Security\SummitScopes;
+use OpenApi\Attributes as OA;
+
+
+
+#[
+    OA\SecurityScheme(
+        type: 'oauth2',
+        securityScheme: 'summit_submitters_oauth2',
+        flows: [
+            new OA\Flow(
+                authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
+                tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+                flow: 'authorizationCode',
+                scopes: [
+                    SummitScopes::ReadSummitData => 'Read summit data',
+                    SummitScopes::ReadAllSummitData => 'Read all summit data',
+                    SummitScopes::WriteSummitData => 'Write summit data',
+                    SummitScopes::WriteSpeakersData => 'Write speakers data',
+                ],
+            ),
+        ],
+    )
+]
+class SummitSubmittersOAuthSchema {}
+

From ef215f7b65ad4bec44a6a1b6a3d26dd383d4352d Mon Sep 17 00:00:00 2001
From: Matias Perrone <github@matiasperrone.com>
Date: Mon, 8 Dec 2025 15:00:11 +0000
Subject: [PATCH 2/2] chore: rename tag

---
 .../Summit/OAuth2SummitSubmittersApiController.php        | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmittersApiController.php b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmittersApiController.php
index d48fcc944..0a4a84827 100644
--- a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmittersApiController.php
+++ b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmittersApiController.php
@@ -74,7 +74,7 @@ public function __construct
         path: "/api/v1/summits/{id}/submitters",
         summary: "Get all submitters for a summit",
         operationId: "getSubmittersBySummit",
-        tags: ["SummitSubmitters"],
+        tags: ["Summit Submitters"],
         security: [['summit_submitters_oauth2' => [
             SummitScopes::ReadSummitData,
             SummitScopes::ReadAllSummitData,
@@ -229,7 +229,7 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use ($summit) {
         description: "required-groups " . IGroup::SummitAdministrators . ", " . IGroup::SuperAdmins . ", " . IGroup::Administrators,
         summary: "Get all submitters for a summit in CSV format",
         operationId: "getSubmittersCSV",
-        tags: ["SummitSubmitters"],
+        tags: ["Summit Submitters"],
         security: [['summit_submitters_oauth2' => [
             SummitScopes::ReadSummitData,
             SummitScopes::ReadAllSummitData,
@@ -378,7 +378,7 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use ($summit) {
         description: "required-groups " . IGroup::SummitAdministrators . ", " . IGroup::SuperAdmins . ", " . IGroup::Administrators . ", " . IGroup::SummitRegistrationAdmins,
         summary: "Send bulk emails to submitters",
         operationId: "sendSubmittersBulkEmails",
-        tags: ["SummitSubmitters"],
+        tags: ["Summit Submitters"],
         security: [['summit_submitters_oauth2' => [
             SummitScopes::WriteSummitData,
             SummitScopes::WriteSpeakersData,
@@ -495,4 +495,4 @@ public function send($summit_id)
             return $this->ok();
         });
     }
-}
\ No newline at end of file
+}