Feature | Extend Swagger Coverage for controller OAuth2SpeakerOrganizationalRoleApiController (#374)

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

* fix: incorrect types and descriptions for errors

* fix: Move schema to the new file

* fix: add the right security schema

* fix: security scopes

* fix: Security schema

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

---------

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

Author: matiasperrone-exo

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

@@ -12,12 +12,16 @@
  * limitations under the License.
  **/
 use App\Models\Foundation\Summit\Repositories\ISpeakerOrganizationalRoleRepository;
+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 OAuth2SpeakerOrganizationalRoleApiController
  * @package App\Http\Controllers
@@ -40,6 +44,36 @@ public function __construct
         $this->repository = $repository;
     }
 
+    #[OA\Get(
+        path: '/api/v1/speakers/organizational-roles',
+        summary: 'Get all default speaker organizational roles',
+        description: 'Retrieves a list of default organizational roles for speakers. These are predefined role types that speakers can select to describe their position or role within an organization (e.g., "Developer", "Manager", "Architect", "Executive").',
+        operationId: 'getAllSpeakerOrganizationalRoles',
+        security: [['speaker_organizational_role_oauth2' => [
+            SummitScopes::ReadSummitData,
+            SummitScopes::ReadAllSummitData
+        ]]],
+        tags: ['Speakers'],
+        parameters: [
+            new OA\Parameter(
+                name: 'expand',
+                in: 'query',
+                required: false,
+                description: 'Comma-separated list of related resources to expand',
+                schema: new OA\Schema(type: 'string', example: '')
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Organizational roles retrieved successfully',
+                content: new OA\JsonContent(ref: '#/components/schemas/SpeakerOrganizationalRolesResponse')
+            ),
+            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
      */
@@ -68,4 +102,4 @@ public function getAll()
             return $this->error500($ex);
         }
     }
-}
+}

app/Swagger/Security/SpeakerOrganizationalRoleAuthSchema.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_organizational_role_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',
+                ],
+            ),
+        ],
+    )
+]
+class SpeakerOrganizationalRoleAuthSchema{}

app/Swagger/SummitSpeakersSchemas.php

@@ -4,6 +4,8 @@
 
 use OpenApi\Attributes as OA;
 
+//
+
 #[OA\Schema(
     schema: 'SpeakerActiveInvolvement',
     type: 'object',
@@ -15,7 +17,9 @@
         new OA\Property(property: 'is_default', type: 'boolean', example: true),
     ]
 )]
-class SpeakerActiveInvolvementSchema {}
+class SpeakerActiveInvolvementSchema
+{
+}
 
 #[OA\Schema(
     schema: 'SpeakerActiveInvolvementsResponse',
@@ -32,4 +36,40 @@ class SpeakerActiveInvolvementSchema {}
         ),
     ]
 )]
-class SpeakerActiveInvolvementsResponseSchema {}
+class SpeakerActiveInvolvementsResponseSchema
+{
+}
+
+#[OA\Schema(
+    schema: 'SpeakerOrganizationalRole',
+    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: 'role', type: 'string', example: 'Developer'),
+        new OA\Property(property: 'is_default', type: 'boolean', example: true),
+    ]
+)]
+class SpeakerOrganizationalRoleSchema
+{
+}
+
+#[OA\Schema(
+    schema: 'SpeakerOrganizationalRolesResponse',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'total', type: 'integer', example: 8),
+        new OA\Property(property: 'per_page', type: 'integer', example: 8),
+        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/SpeakerOrganizationalRole')
+        ),
+    ]
+)]
+class SpeakerOrganizationalRolesResponseSchema
+{
+}