feat: Add OpenAPI documentation to "getAll" method

- Add controller's response to OpenAPI schema

Author: matiasperrone-exo

app/Http/Controllers/Apis/Protected/Main/OAuth2GroupsApiController.php

@@ -12,9 +12,12 @@
  * limitations under the License.
  **/
 
+use App\Security\SummitScopes;
+use Illuminate\Http\Response;
 use models\main\IGroupRepository;
 use models\oauth2\IResourceServerContext;
 use ModelSerializers\SerializerRegistry;
+use OpenApi\Attributes as OA;
 
 /**
  * Class OAuth2GroupsApiController
@@ -40,6 +43,77 @@ public function __construct
         $this->repository = $group_repository;
     }
 
+    #[OA\Get(
+        path: "/api/v1/groups",
+        description: "Get all groups with filtering and pagination. Groups are used for access control and organization of members. Requires OAuth2 authentication with appropriate scope.",
+        summary: 'Get all groups',
+        operationId: 'getAllGroups',
+        tags: ['Groups'],
+        security: [['summit_rsvp_oauth2' => [
+            SummitScopes::ReadAllSummitData,
+        ]]],
+        parameters: [
+            new OA\Parameter(
+                name: 'access_token',
+                in: 'query',
+                required: false,
+                description: 'OAuth2 access token (alternative to Authorization: Bearer)',
+                schema: new OA\Schema(type: 'string', example: 'eyJhbGciOi...')
+            ),
+            new OA\Parameter(
+                name: 'page',
+                in: 'query',
+                required: false,
+                description: 'Page number for pagination',
+                schema: new OA\Schema(type: 'integer', example: 1)
+            ),
+            new OA\Parameter(
+                name: 'per_page',
+                in: 'query',
+                required: false,
+                description: 'Items per page',
+                schema: new OA\Schema(type: 'integer', example: 10, maximum: 100)
+            ),
+            new OA\Parameter(
+                name: 'filter[]',
+                in: 'query',
+                required: false,
+                description: 'Filter expressions. Format: field<op>value. Available fields: code (=@, ==, @@), title (=@, ==, @@). Operators: == (equals), =@ (starts with), @@ (contains)',
+                style: 'form',
+                explode: true,
+                schema: new OA\Schema(
+                    type: 'array',
+                    items: new OA\Items(type: 'string', example: 'code==administrators')
+                )
+            ),
+            new OA\Parameter(
+                name: 'order',
+                in: 'query',
+                required: false,
+                description: 'Order by field(s). Available fields: code, title, id. Use "-" prefix for descending order.',
+                schema: new OA\Schema(type: 'string', example: 'title')
+            ),
+            new OA\Parameter(
+                name: 'expand',
+                in: 'query',
+                required: false,
+                description: 'Comma-separated list of related resources to include. Available relations: members',
+                schema: new OA\Schema(type: 'string', example: 'members')
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Success - Returns paginated list of groups',
+                content: new OA\JsonContent(ref: '#/components/schemas/PaginatedGroupsResponse')
+            ),
+            new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request - Invalid parameters"),
+            new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized - Invalid or missing access token"),
+            new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden - Insufficient permissions"),
+            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 getAll()
     {
         return $this->_getAll(
@@ -71,4 +145,4 @@ function () {
         );
     }
 
-}
+}

app/Swagger/schemas.php

@@ -376,3 +376,35 @@ class RSVPUpdateRequestSchema_{
     ]
 )]
 class RSVPAdminAddRequestSchema {}
+
+#[OA\Schema(
+    schema: 'Group',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1, description: 'Unique identifier'),
+        new OA\Property(property: 'created', type: 'integer', example: 1630500518, description: 'Creation timestamp (Unix epoch)'),
+        new OA\Property(property: 'last_edited', type: 'integer', example: 1630500518, description: 'Last modification timestamp (Unix epoch)'),
+        new OA\Property(property: 'title', type: 'string', example: 'Administrators', description: 'Group title'),
+        new OA\Property(property: 'description', type: 'string', example: 'System administrators group', description: 'Group description', nullable: true),
+        new OA\Property(property: 'code', type: 'string', example: 'administrators', description: 'Unique group code'),
+    ]
+)]
+class GroupSchema {}
+
+#[OA\Schema(
+    schema: 'PaginatedGroupsResponse',
+    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/Group')
+                )
+            ]
+        )
+    ]
+)]
+class PaginatedGroupsResponseSchema {}