Feature | Extend Swagger Coverage for controller LanguagesApiController (#358)

* feat: Add OpenAPI documentation to "getAll" method

* fix: Open API path to endpoint

* fix: Reuse already defined schema and add Paginated Schema

Author: matiasperrone-exo

app/Http/Controllers/Apis/LanguagesApiController.php

@@ -12,17 +12,16 @@
  * limitations under the License.
  **/
 use App\Models\Foundation\Main\Repositories\ILanguageRepository;
-use Illuminate\Support\Facades\Log;
-use models\exceptions\EntityNotFoundException;
-use models\exceptions\ValidationException;
+use Illuminate\Http\Response;
+use OpenApi\Attributes as OA;
 use utils\PagingResponse;
-use Illuminate\Support\Facades\Request;
 /**
  * Class LanguagesApiController
  * @package App\Http\Controllers
  */
 final class LanguagesApiController extends JsonController
 {
+    use RequestProcessor;
     /**
      * @var ILanguageRepository
      */
@@ -37,13 +36,28 @@ public function __construct(ILanguageRepository $language_repository)
         $this->language_repository = $language_repository;
     }
 
-    /**
-     * @return mixed
-     */
-    public function getAll(){
-        try {
-            $languages   = $this->language_repository->getAll();
-            $response    = new PagingResponse
+    #[OA\Get(
+        path: "/api/public/v1/languages",
+        description: "Get all available languages with ISO codes",
+        summary: 'Get all languages',
+        operationId: 'getAllLanguages',
+        tags: ['Languages'],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Success - Returns paginated list of languages',
+                content: new OA\JsonContent(ref: '#/components/schemas/PaginatedISOLanguageElementResponseSchema'),
+            ),
+            new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error")
+        ]
+    )]
+    public function getAll()
+    {
+        return $this->processRequest(function () {
+            $languages = $this->language_repository->getAll();
+            $response = new PagingResponse
             (
                 count($languages),
                 count($languages),
@@ -52,20 +66,8 @@ public function getAll(){
                 $languages
             );
 
-            return $this->ok($response->toArray($expand = Request::input('expand','')));
-        }
-        catch (ValidationException $ex1) {
-            Log::warning($ex1);
-            return $this->error412(array($ex1->getMessage()));
-        }
-        catch(EntityNotFoundException $ex2)
-        {
-            Log::warning($ex2);
-            return $this->error404(array('message'=> $ex2->getMessage()));
-        }
-        catch (\Exception $ex) {
-            Log::error($ex);
-            return $this->error500($ex);
-        }
+            return $this->ok($response->toArray());
+        });
     }
-}
+
+}

app/Swagger/Countries.php

@@ -10,7 +10,7 @@
         'name' => new OA\Property(property: 'name', type: 'string', example: 'United States')
     ]
 )]
-class ISOElementSchema {};
+class ISOCountryElementSchema {};
 
 #[OA\Schema(
     schema: 'PaginatedISOCountryElementResponseSchema',
@@ -29,4 +29,4 @@ class ISOElementSchema {};
         )
     ]
 )]
-class PaginatedISOElementResponseSchema {};
+class PaginatedISOCountryElementResponseSchema {};

app/Swagger/Languages.php

@@ -0,0 +1,32 @@
+<?php namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'ISOLanguageElementSchema',
+    type: 'object',
+    properties: [
+        'iso_code' => new OA\Property(property: 'iso_code', type: 'string', example: 'US'),
+        'name' => new OA\Property(property: 'name', type: 'string', example: 'United States')
+    ]
+)]
+class ISOLanguageElementSchema {};
+
+#[OA\Schema(
+    schema: 'PaginatedISOLanguageElementResponseSchema',
+    type: 'object',
+    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/ISOLanguageElementSchema")
+                )
+            ]
+        )
+    ]
+)]
+class PaginatedISOLanguageElementResponseSchema {};

start_local_server.sh

@@ -6,6 +6,7 @@ export DOCKER_SCAN_SUGGEST=false
 docker compose up -d app
 # Run all setup commands inside the running container
 docker compose exec app composer install
+docker compose exec app composer dump-autoload -o
 docker compose exec app php artisan db:create_test_db --schema=config
 docker compose exec app php artisan db:create_test_db --schema=model
 docker compose exec app php artisan doctrine:migrations:migrate --no-interaction --em=config
@@ -17,4 +18,4 @@ docker compose exec app php artisan l5-swagger:generate
 # Now bring up all remaining services
 docker compose up -d
 # Open shell as appuser
-docker compose exec app /bin/bash
+docker compose exec app /bin/bash