Feature | Extend Swagger Coverage for controller OAuth2SummitRegistrationCompaniesApiController

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,39 @@ 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: ["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)),
+            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 +139,80 @@ 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: ["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")),
+        ],
+        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: ["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")),
+        ],
+        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 +221,46 @@ 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: ["Registration Companies"],
+        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);
@@ -166,4 +289,4 @@ public function import(LaravelRequest $request,$summit_id){
 
         });
     }
-}
+}

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

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