From 9415bc2ed54e6a71d050a596dd7ba52485c13cd4 Mon Sep 17 00:00:00 2001
From: Jose Andres Tejerina <andres.tejerina@exomindset.co>
Date: Fri, 14 Nov 2025 15:47:31 -0300
Subject: [PATCH 1/3] feat: Add openapi documentation for
 OAuth2SummitRegistrationCompaniesApiController

---
 ...mmitRegistrationCompaniesApiController.php | 147 +++++++++++++++---
 app/Swagger/RegistrationCompaniesSchemas.php  |  70 +++++++++
 .../Security/RegistrationCompaniesOauth2.php  |  25 +++
 3 files changed, 222 insertions(+), 20 deletions(-)
 create mode 100644 app/Swagger/RegistrationCompaniesSchemas.php
 create mode 100644 app/Swagger/Security/RegistrationCompaniesOauth2.php

diff --git a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php
index f886d1e7d..81ead84a8 100644
--- a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php
+++ b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php
@@ -12,13 +12,17 @@
  * limitations under the License.
  **/
 
+use App\Models\Foundation\Main\IGroup;
+use App\Security\SummitScopes;
 use Illuminate\Http\Request as LaravelRequest;
 use Illuminate\Support\Facades\Validator;
 use models\exceptions\ValidationException;
 use models\oauth2\IResourceServerContext;
 use models\summit\ISummitRepository;
 use ModelSerializers\SerializerRegistry;
+use OpenApi\Attributes as OA;
 use services\model\ISummitService;
+use Symfony\Component\HttpFoundation\Response;
 use utils\PagingInfo;
 
 /**
@@ -60,10 +64,35 @@ public function __construct
         $this->summit_service = $summit_service;
     }
 
-    /**
-     * @param $summit_id
-     * @return mixed
-     */
+    #[OA\Get(
+        path: "/api/v1/summits/{id}/registration-companies",
+        summary: "Get all registration companies for a summit",
+        description: "Returns list of companies that have registered attendees for this summit",
+        security: [["registration_companies_oauth2" => [
+            SummitScopes::ReadAllSummitData,
+            SummitScopes::ReadSummitData,
+        ]]],
+        tags: ["RegistrationCompanies"],
+        parameters: [
+            new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
+            new OA\Parameter(name: "page", description: "Page number", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 1)),
+            new OA\Parameter(name: "per_page", description: "Items per page", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 10)),
+            new OA\Parameter(name: "filter", description: "Filter query (name==value, name=@value, name@@value)", in: "query", required: false, schema: new OA\Schema(type: "string")),
+            new OA\Parameter(name: "order", description: "Order by (+name, -name)", in: "query", required: false, schema: new OA\Schema(type: "string")),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: "OK",
+                content: new OA\JsonContent(ref: "#/components/schemas/PaginatedCompaniesResponse")
+            ),
+            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: "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($summit_id);
@@ -106,25 +135,72 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use($summit) {
         );
     }
 
-    /**
-     * @param $summit_id
-     * @param $company_id
-     * @return mixed
-     */
+    #[OA\Put(
+        path: "/api/v1/summits/{id}/registration-companies/{company_id}",
+        summary: "Add a company to summit registration companies",
+        description: "Associates a company with the summit for registration purposes (requires admin privileges)",
+        x: [
+            'required-groups' => [
+                IGroup::SuperAdmins,
+                IGroup::Administrators,
+                IGroup::SummitAdministrators,
+                IGroup::TrackChairsAdmins,
+            ]
+        ],
+        security: [["registration_companies_oauth2" => [
+            SummitScopes::WriteSummitData,
+        ]]],
+        tags: ["RegistrationCompanies"],
+        parameters: [
+            new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
+            new OA\Parameter(name: "company_id", description: "Company ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
+        ],
+        responses: [
+            new OA\Response(response: Response::HTTP_CREATED, description: "Created"),
+            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: "not found"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
     public function add($summit_id, $company_id)
     {
-
         return $this->processRequest(function() use($summit_id, $company_id){
             $this->summit_service->addCompany(intval($summit_id), intval($company_id));
             return $this->created();
         });
     }
 
-    /**
-     * @param $summit_id
-     * @param $company_id
-     * @return mixed
-     */
+    #[OA\Delete(
+        path: "/api/v1/summits/{id}/registration-companies/{company_id}",
+        summary: "Remove a company from summit registration companies",
+        description: "Disassociates a company from the summit registration (requires admin privileges)",
+        x: [
+            'required-groups' => [
+                IGroup::SuperAdmins,
+                IGroup::Administrators,
+                IGroup::SummitAdministrators,
+                IGroup::TrackChairsAdmins,
+            ]
+        ],
+        security: [["registration_companies_oauth2" => [
+            SummitScopes::WriteSummitData,
+        ]]],
+        tags: ["RegistrationCompanies"],
+        parameters: [
+            new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
+            new OA\Parameter(name: "company_id", description: "Company ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
+        ],
+        responses: [
+            new OA\Response(response: Response::HTTP_NO_CONTENT, description: "No Content"),
+            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: "not found"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
     public function delete($summit_id, $company_id)
     {
         return $this->processRequest(function() use($summit_id, $company_id){
@@ -133,11 +209,42 @@ public function delete($summit_id, $company_id)
         });
     }
 
-    /**
-     * @param LaravelRequest $request
-     * @param $summit_id
-     * @return mixed
-     */
+    #[OA\Post(
+        path: "/api/v1/summits/{id}/registration-companies/csv",
+        summary: "Import registration companies from CSV file",
+        description: "Bulk import companies for summit registration from a CSV file (requires admin privileges)",
+        x: [
+            'required-groups' => [
+                IGroup::SuperAdmins,
+                IGroup::Administrators,
+                IGroup::SummitAdministrators,
+                IGroup::TrackChairsAdmins,
+            ]
+        ],
+        security: [["registration_companies_oauth2" => [
+            SummitScopes::WriteSummitData,
+        ]]],
+        tags: ["RegistrationCompanies"],
+        parameters: [
+            new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
+        ],
+        requestBody: new OA\RequestBody(
+            required: true,
+            content: new OA\MediaType(
+                mediaType: "multipart/form-data",
+                schema: new OA\Schema(ref: "#/components/schemas/ImportRegistrationCompaniesRequest")
+            )
+        ),
+        responses: [
+            new OA\Response(response: Response::HTTP_OK, description: "OK - Companies imported 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: "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 import(LaravelRequest $request,$summit_id){
         return $this->processRequest(function() use($request, $summit_id){
             $summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
diff --git a/app/Swagger/RegistrationCompaniesSchemas.php b/app/Swagger/RegistrationCompaniesSchemas.php
new file mode 100644
index 000000000..1531a520e
--- /dev/null
+++ b/app/Swagger/RegistrationCompaniesSchemas.php
@@ -0,0 +1,70 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'Company',
+    type: 'object',
+    description: 'Base company information (public view)',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer'),
+        new OA\Property(property: 'created', type: 'integer'),
+        new OA\Property(property: 'last_edited', type: 'integer'),
+        new OA\Property(property: 'name', type: 'string'),
+        new OA\Property(property: 'url', type: 'string', format: 'url', nullable: true),
+        new OA\Property(property: 'url_segment', type: 'string', nullable: true),
+        new OA\Property(property: 'city', type: 'string', nullable: true),
+        new OA\Property(property: 'state', type: 'string', nullable: true),
+        new OA\Property(property: 'country', type: 'string', nullable: true),
+        new OA\Property(property: 'description', type: 'string', nullable: true),
+        new OA\Property(property: 'industry', type: 'string', nullable: true),
+        new OA\Property(property: 'contributions', type: 'string', nullable: true),
+        new OA\Property(property: 'member_level', type: 'string', nullable: true),
+        new OA\Property(property: 'overview', type: 'string', nullable: true),
+        new OA\Property(property: 'products', type: 'string', nullable: true),
+        new OA\Property(property: 'commitment', type: 'string', nullable: true),
+        new OA\Property(property: 'commitment_author', type: 'string', nullable: true),
+        new OA\Property(property: 'logo', type: 'string', format: 'url', nullable: true),
+        new OA\Property(property: 'big_logo', type: 'string', format: 'url', nullable: true),
+        new OA\Property(property: 'color', type: 'string', description: 'Hex color code', nullable: true),
+    ]
+)]
+class CompanySchema {}
+
+#[OA\Schema(
+    schema: 'PaginatedCompaniesResponse',
+    type: 'object',
+    description: 'Paginated response for registration companies',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: 'data',
+                    type: 'array',
+                    items: new OA\Items(ref: '#/components/schemas/Company')
+                )
+            ]
+        )
+    ]
+)]
+class PaginatedCompaniesResponseSchema {}
+
+#[OA\Schema(
+    schema: 'ImportRegistrationCompaniesRequest',
+    type: 'object',
+    description: 'Request to import registration companies from CSV file',
+    required: ['file'],
+    properties: [
+        new OA\Property(
+            property: 'file',
+            type: 'string',
+            format: 'binary',
+            description: 'CSV file with company data'
+        ),
+    ]
+)]
+class ImportRegistrationCompaniesRequestSchema {}
diff --git a/app/Swagger/Security/RegistrationCompaniesOauth2.php b/app/Swagger/Security/RegistrationCompaniesOauth2.php
new file mode 100644
index 000000000..8cfa24420
--- /dev/null
+++ b/app/Swagger/Security/RegistrationCompaniesOauth2.php
@@ -0,0 +1,25 @@
+<?php 
+namespace App\Swagger\schemas;
+
+use App\Security\SummitScopes;
+use OpenApi\Attributes as OA;
+
+#[
+    OA\SecurityScheme(
+        type: 'oauth2',
+        securityScheme: 'registration_companies_oauth2',
+        flows: [
+            new OA\Flow(
+                authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
+                tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+                flow: 'authorizationCode',
+                scopes: [
+                    SummitScopes::ReadAllSummitData => 'Read All Summit Data',
+                    SummitScopes::ReadSummitData => 'Read Summit Data',
+                    SummitScopes::WriteSummitData => 'Write Summit Data',
+                ],
+            ),
+        ],
+    )
+]
+class RegistrationCompaniesAuthSchema{}

From 461c11daedd0ee46e1b02c07a328242a9074379d Mon Sep 17 00:00:00 2001
From: Matias Perrone <github@matiasperrone.com>
Date: Tue, 9 Dec 2025 21:02:48 +0000
Subject: [PATCH 2/3] chore: Add PR's requested changes

---
 .../OAuth2SummitRegistrationCompaniesApiController.php | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php
index 81ead84a8..39d356e53 100644
--- a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php
+++ b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php
@@ -72,7 +72,7 @@ public function __construct
             SummitScopes::ReadAllSummitData,
             SummitScopes::ReadSummitData,
         ]]],
-        tags: ["RegistrationCompanies"],
+        tags: ["Registration Companies"],
         parameters: [
             new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
             new OA\Parameter(name: "page", description: "Page number", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 1)),
@@ -150,7 +150,7 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use($summit) {
         security: [["registration_companies_oauth2" => [
             SummitScopes::WriteSummitData,
         ]]],
-        tags: ["RegistrationCompanies"],
+        tags: ["Registration Companies"],
         parameters: [
             new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
             new OA\Parameter(name: "company_id", description: "Company ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
@@ -187,7 +187,7 @@ public function add($summit_id, $company_id)
         security: [["registration_companies_oauth2" => [
             SummitScopes::WriteSummitData,
         ]]],
-        tags: ["RegistrationCompanies"],
+        tags: ["Registration Companies"],
         parameters: [
             new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
             new OA\Parameter(name: "company_id", description: "Company ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
@@ -224,7 +224,7 @@ public function delete($summit_id, $company_id)
         security: [["registration_companies_oauth2" => [
             SummitScopes::WriteSummitData,
         ]]],
-        tags: ["RegistrationCompanies"],
+        tags: ["Registration Companies"],
         parameters: [
             new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
         ],
@@ -273,4 +273,4 @@ public function import(LaravelRequest $request,$summit_id){
 
         });
     }
-}
\ No newline at end of file
+}

From 03f950196522c760802e1761370d337988389344 Mon Sep 17 00:00:00 2001
From: Matias Perrone <github@matiasperrone.com>
Date: Tue, 9 Dec 2025 21:33:41 +0000
Subject: [PATCH 3/3] chore: Add PR's requested changes

---
 ...mmitRegistrationCompaniesApiController.php | 50 ++++++++++++-------
 1 file changed, 33 insertions(+), 17 deletions(-)

diff --git a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php
index 39d356e53..e3938c51b 100644
--- a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php
+++ b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitRegistrationCompaniesApiController.php
@@ -68,10 +68,14 @@ public function __construct
         path: "/api/v1/summits/{id}/registration-companies",
         summary: "Get all registration companies for a summit",
         description: "Returns list of companies that have registered attendees for this summit",
-        security: [["registration_companies_oauth2" => [
-            SummitScopes::ReadAllSummitData,
-            SummitScopes::ReadSummitData,
-        ]]],
+        security: [
+            [
+                "registration_companies_oauth2" => [
+                    SummitScopes::ReadAllSummitData,
+                    SummitScopes::ReadSummitData,
+                ]
+            ]
+        ],
         tags: ["Registration Companies"],
         parameters: [
             new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
@@ -89,7 +93,7 @@ public function __construct
             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: "not found"),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
             new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
         ]
     )]
@@ -147,9 +151,13 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use($summit) {
                 IGroup::TrackChairsAdmins,
             ]
         ],
-        security: [["registration_companies_oauth2" => [
-            SummitScopes::WriteSummitData,
-        ]]],
+        security: [
+            [
+                "registration_companies_oauth2" => [
+                    SummitScopes::WriteSummitData,
+                ]
+            ]
+        ],
         tags: ["Registration Companies"],
         parameters: [
             new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
@@ -160,7 +168,7 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use($summit) {
             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: "not found"),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
             new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
         ]
     )]
@@ -184,9 +192,13 @@ public function add($summit_id, $company_id)
                 IGroup::TrackChairsAdmins,
             ]
         ],
-        security: [["registration_companies_oauth2" => [
-            SummitScopes::WriteSummitData,
-        ]]],
+        security: [
+            [
+                "registration_companies_oauth2" => [
+                    SummitScopes::WriteSummitData,
+                ]
+            ]
+        ],
         tags: ["Registration Companies"],
         parameters: [
             new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
@@ -197,7 +209,7 @@ public function add($summit_id, $company_id)
             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: "not found"),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
             new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
         ]
     )]
@@ -221,9 +233,13 @@ public function delete($summit_id, $company_id)
                 IGroup::TrackChairsAdmins,
             ]
         ],
-        security: [["registration_companies_oauth2" => [
-            SummitScopes::WriteSummitData,
-        ]]],
+        security: [
+            [
+                "registration_companies_oauth2" => [
+                    SummitScopes::WriteSummitData,
+                ]
+            ]
+        ],
         tags: ["Registration Companies"],
         parameters: [
             new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
@@ -240,7 +256,7 @@ public function delete($summit_id, $company_id)
             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: "not found"),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "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"),
         ]