Feature | Extend Swagger Coverage for controller OAuth2GroupsApiController

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

@@ -1,4 +1,5 @@
-<?php namespace App\Http\Controllers;
+<?php
+namespace App\Http\Controllers;
 /**
  * Copyright 2017 OpenStack Foundation
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,9 +13,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
@@ -26,20 +30,96 @@ final class OAuth2GroupsApiController extends OAuth2ProtectedController
     use ParametrizedGetAll;
 
     /**
-     * OAuth2MembersApiController constructor.
+     * OAuth2GroupsApiController constructor.
      * @param IGroupRepository $group_repository
      * @param IResourceServerContext $resource_server_context
      */
     public function __construct
     (
-        IGroupRepository       $group_repository,
+        IGroupRepository $group_repository,
         IResourceServerContext $resource_server_context
-    )
-    {
+    ) {
         parent::__construct($resource_server_context);
         $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: [
+            [
+                'groups_oauth2' => [
+                    SummitScopes::ReadAllSummitData,
+                    SummitScopes::ReadSummitData,
+                    SummitScopes::ReadGroupsData,
+                ]
+            ]
+        ],
+        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 (expands member IDs to full member objects)',
+                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 +151,4 @@ function () {
         );
     }
 
-}
+}

app/Security/SummitScopes.php

@@ -1,4 +1,5 @@
-<?php namespace App\Security;
+<?php
+namespace App\Security;
 /**
  * Copyright 2017 OpenStack Foundation
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -119,4 +120,6 @@ final class SummitScopes
 
     const WriteAttendeeNotesData = '%s/attendee/notes/write';
     const ReadAttendeeNotesData = '%s/attendee/notes/read';
-}
+
+    const ReadGroupsData = '%s/groups/read';
+}

app/Swagger/Models/GroupSchema.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[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'),
+        new OA\Property(
+            property: 'members',
+            type: 'array',
+            description: 'List of Member objects, only present when requested via ?expand=members',
+            items: new OA\Items(
+                ref: '#/components/schemas/Member'
+            )
+        ),
+    ]
+)]
+class GroupSchema
+{
+}

app/Swagger/Security/GroupsOAuthSchema.php

@@ -0,0 +1,26 @@
+<?php
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+use App\Security\SummitScopes;
+
+#[OA\SecurityScheme(
+    type: 'oauth2',
+    securityScheme: 'groups_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::ReadGroupsData => 'Read Groups Data',
+            ],
+        ),
+    ],
+)
+]
+class GroupsOAuthSchema
+{
+}

app/Swagger/schemas.php

@@ -579,6 +579,28 @@ class PaymentGatewayProfileCreateRequestSchema
 class PaymentGatewayProfileUpdateRequestSchema
 {
 }
+
+
+#[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
+{
+}
+
 // User Stories