feat: Extend Swagger Coverage for controller TimezonesApiController

Author: andrestejerina97

app/Http/Controllers/Apis/TimezonesApiController.php

@@ -1,4 +1,5 @@
 <?php namespace App\Http\Controllers;
+
 /**
  * Copyright 2021 OpenStack Foundation
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,6 +18,9 @@
 use models\exceptions\EntityNotFoundException;
 use models\exceptions\ValidationException;
 use utils\PagingResponse;
+use OpenApi\Attributes as OA;
+use Symfony\Component\HttpFoundation\Response;
+
 /**
  * Class TimezonesApiController
  * @package App\Http\Controllers
@@ -26,6 +30,80 @@ final class TimezonesApiController extends JsonController
     /**
      * @return mixed
      */
+    #[OA\Get(
+        path: '/api/v1/timezones',
+        operationId: 'getTimezones',
+        description: 'Retrieve all available timezones',
+        tags: ['Timezones'],
+        parameters: [
+            new OA\Parameter(
+                name: 'expand',
+                description: 'Expansion parameters',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
+            new OA\Parameter(
+                name: 'page',
+                description: 'Page number',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'integer', default: 1)
+            ),
+            new OA\Parameter(
+                name: 'per_page',
+                description: 'Items per page',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'integer', default: 10)
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: 'List of timezones',
+                content: new OA\JsonContent(
+                    properties: [
+                        new OA\Property(
+                            property: 'data',
+                            type: 'array',
+                            items: new OA\Items(
+                                type: 'string',
+                                example: 'America/New_York'
+                            ),
+                            description: 'Array of timezone identifiers'
+                        ),
+                        new OA\Property(
+                            property: 'total',
+                            type: 'integer',
+                            description: 'Total number of timezones',
+                            example: 427
+                        ),
+                        new OA\Property(
+                            property: 'page',
+                            type: 'integer',
+                            description: 'Current page number',
+                            example: 1
+                        ),
+                        new OA\Property(
+                            property: 'last_page',
+                            type: 'integer',
+                            description: 'Last page number',
+                            example: 1
+                        ),
+                    ]
+                )
+            ),
+            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(){
         try {
             $timezones   = \DateTimeZone::listIdentifiers();

app/Swagger/schemas.php

@@ -351,3 +351,22 @@ class RSVPUpdateRequestSchema_{
     ]
 )]
 class RSVPAdminAddRequestSchema {}
+
+#[OA\Schema(
+    schema: 'PaginatedTimezonesResponse',
+    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(type: 'string', example: 'America/New_York'),
+                    description: 'Array of timezone identifiers'
+                )
+            ]
+        )
+    ]
+)]
+class PaginatedTimezonesResponseSchema {}