Feature | Extend Swagger Coverage for controller OAuth2SpeakerActiveInvolvementApiController (#373)

* feat: Extend Swagger Coverage for controller Apis/Protected/Summit/OAuth2SpeakerActiveInvolvementApiController.php

* fix: incorrect types and descriptions for errors

* fix: Move schema to the new file

* fix: Change "namespace" word positioning

* chore: Add security param

* fix: security scopes

* fix: Security schema

* chore: Move the security schema for the controller to its own file

* chore: include PR requested changes

---------

Co-authored-by: Matias Perrone <github@matiasperrone.com>

Author: matiasperrone-exo

app/Http/Controllers/Apis/Protected/Summit/OAuth2SpeakerActiveInvolvementApiController.php

@@ -1,4 +1,7 @@
-<?php namespace App\Http\Controllers;
+<?php
+
+namespace App\Http\Controllers;
+
 /**
  * Copyright 2018 OpenStack Foundation
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,12 +15,16 @@
  * limitations under the License.
  **/
 use App\Models\Foundation\Summit\Repositories\ISpeakerActiveInvolvementRepository;
+use App\Security\SummitScopes;
 use models\oauth2\IResourceServerContext;
 use Illuminate\Support\Facades\Log;
 use models\exceptions\EntityNotFoundException;
 use models\exceptions\ValidationException;
+use Symfony\Component\HttpFoundation\Response;
 use utils\PagingResponse;
 use Illuminate\Support\Facades\Request;
+use OpenApi\Attributes as OA;
+
 /**
  * Class OAuth2SpeakerActiveInvolvementApiController
  * @package App\Http\Controllers
@@ -34,12 +41,45 @@ public function __construct
     (
         ISpeakerActiveInvolvementRepository $repository,
         IResourceServerContext $resource_server_context
-    )
-    {
+    ) {
         parent::__construct($resource_server_context);
         $this->repository = $repository;
     }
 
+    #[OA\Get(
+        path: '/api/v1/speakers/active-involvements',
+        summary: 'Get all default speaker active involvements',
+        description: 'Retrieves a list of default active involvements for speakers. These are predefined involvement types that speakers can select to describe their current activities (e.g., "Active Contributor", "User", "Evaluator").',
+        operationId: 'getAllSpeakerActiveInvolvements',
+        security: [
+            [
+                'speaker_active_involvement_oauth2' => [
+                    SummitScopes::ReadSummitData,
+                    SummitScopes::ReadAllSummitData,
+                ]
+            ]
+        ],
+        tags: ['Speakers'],
+        parameters: [
+            new OA\Parameter(
+                name: 'expand',
+                in: 'query',
+                required: false,
+                description: 'No expandable relationships available for this resource',
+                schema: new OA\Schema(type: 'string', example: '')
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Active involvements retrieved successfully',
+                content: new OA\JsonContent(ref: '#/components/schemas/SpeakerActiveInvolvementsResponse')
+            ),
+            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"),
+        ]
+    )]
     /**
      * @return mixed
      */
@@ -71,4 +111,4 @@ public function getAll(){
             return $this->error500($ex);
         }
     }
-}
+}

app/Swagger/Security/SpeakerActiveInvolvementAuthSchema.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use App\Security\SummitScopes;
+use OpenApi\Attributes as OA;
+
+
+#[OA\SecurityScheme(
+        type: 'oauth2',
+        securityScheme: 'speaker_active_involvement_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',
+                ],
+            ),
+        ],
+    )
+]
+class SpeakerActiveInvolvementAuthSchema{}

app/Swagger/SummitSpeakersSchemas.php

@@ -4,4 +4,32 @@
 
 use OpenApi\Attributes as OA;
 
-//
+#[OA\Schema(
+    schema: 'SpeakerActiveInvolvement',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'created', type: 'integer', format: 'int64', example: 1633024800),
+        new OA\Property(property: 'last_edited', type: 'integer', format: 'int64', example: 1633024800),
+        new OA\Property(property: 'involvement', type: 'string', example: 'Active Contributor'),
+        new OA\Property(property: 'is_default', type: 'boolean', example: true),
+    ]
+)]
+class SpeakerActiveInvolvementSchema {}
+
+#[OA\Schema(
+    schema: 'SpeakerActiveInvolvementsResponse',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'total', type: 'integer', example: 5),
+        new OA\Property(property: 'per_page', type: 'integer', example: 5),
+        new OA\Property(property: 'current_page', type: 'integer', example: 1),
+        new OA\Property(property: 'last_page', type: 'integer', example: 1),
+        new OA\Property(
+            property: 'data',
+            type: 'array',
+            items: new OA\Items(ref: '#/components/schemas/SpeakerActiveInvolvement')
+        ),
+    ]
+)]
+class SpeakerActiveInvolvementsResponseSchema {}