diff --git a/app/Http/Controllers/Apis/Protected/Main/OAuth2GroupsApiController.php b/app/Http/Controllers/Apis/Protected/Main/OAuth2GroupsApiController.php index 067783469..6d91c5519 100644 --- a/app/Http/Controllers/Apis/Protected/Main/OAuth2GroupsApiController.php +++ b/app/Http/Controllers/Apis/Protected/Main/OAuth2GroupsApiController.php @@ -1,4 +1,5 @@ -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: fieldvalue. 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 () { ); } -} \ No newline at end of file +} diff --git a/app/Security/SummitScopes.php b/app/Security/SummitScopes.php index f8869c38b..9470449a2 100644 --- a/app/Security/SummitScopes.php +++ b/app/Security/SummitScopes.php @@ -1,4 +1,5 @@ - 'Read All Summit Data', + SummitScopes::ReadSummitData => 'Read Summit Data', + SummitScopes::ReadGroupsData => 'Read Groups Data', + ], + ), + ], +) +] +class GroupsOAuthSchema +{ +} diff --git a/app/Swagger/schemas.php b/app/Swagger/schemas.php index b940875b5..f7b7470ff 100644 --- a/app/Swagger/schemas.php +++ b/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