feat: Add OpenAPI documentation to "getAll" and "add" methods

- Add controller's response to OpenAPI schema

Author: matiasperrone-exo

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

@@ -1,4 +1,7 @@
-<?php namespace App\Http\Controllers;
+<?php
+
+namespace App\Http\Controllers;
+
 /**
  * Copyright 2018 OpenStack Foundation
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,11 +15,14 @@
  * limitations under the License.
  **/
 
+use App\Security\SummitScopes;
 use App\Services\Model\IOrganizationService;
+use Illuminate\Http\Response;
 use models\main\IOrganizationRepository;
 use models\oauth2\IResourceServerContext;
 use models\utils\IEntity;
 use ModelSerializers\SerializerRegistry;
+use OpenApi\Attributes as OA;
 
 /**
  * Class OAuth2OrganizationsApiController
@@ -30,6 +36,31 @@ final class OAuth2OrganizationsApiController extends OAuth2ProtectedController
     private $service;
 
     use ParametrizedGetAll;
+    use AddEntity;
+
+    #[OA\Post(
+        path: '/api/v1/organizations',
+        summary: 'Creates a new organization',
+        security: [['oauth2_security_scope' => [SummitScopes::ReadAllSummitData, SummitScopes::WriteSummitData]]],
+        tags: ['organizations'],
+        requestBody: new OA\RequestBody(
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/OrganizationCreateRequest')
+        ),
+        responses: [
+            new OA\Response(
+                response: 201,
+                description: 'Organization created successfully',
+                content: new OA\JsonContent(ref: '#/components/schemas/Organization')
+            ),
+            new OA\Response(response: 400, ref: '#/components/responses/400'),
+            new OA\Response(response: 401, ref: '#/components/responses/401'),
+            new OA\Response(response: 403, ref: '#/components/responses/403'),
+            new OA\Response(response: 412, ref: '#/components/responses/412'),
+            new OA\Response(response: 422, ref: '#/components/responses/422'),
+            new OA\Response(response: 500, ref: '#/components/responses/500'),
+        ]
+    )]
 
     /**
      * OAuth2OrganizationsApiController constructor.
@@ -49,6 +80,70 @@ public function __construct
         $this->service = $service;
     }
 
+    #[OA\Get(
+        path: "/api/v1/organizations",
+        description: "Get all organizations with filtering and pagination. Organizations represent companies, foundations, or entities in the system. Requires OAuth2 authentication with appropriate scope.",
+        summary: 'Get all organizations',
+        operationId: 'getAllOrganizations',
+        tags: ['Organizations'],
+        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 field: name (=@, ==, @@). Operators: == (equals), =@ (starts with), @@ (contains)',
+                style: 'form',
+                explode: true,
+                schema: new OA\Schema(
+                    type: 'array',
+                    items: new OA\Items(type: 'string', example: 'name@@OpenStack')
+                )
+            ),
+            new OA\Parameter(
+                name: 'order',
+                in: 'query',
+                required: false,
+                description: 'Order by field(s). Available fields: name, id. Use "-" prefix for descending order.',
+                schema: new OA\Schema(type: 'string', example: 'name')
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Success - Returns paginated list of organizations',
+                content: new OA\JsonContent(ref: '#/components/schemas/PaginatedOrganizationsResponse')
+            ),
+            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(
@@ -77,7 +172,6 @@ function () {
         );
     }
 
-    use AddEntity;
 
     /**
      * @inheritDoc
@@ -96,4 +190,4 @@ protected function addEntity(array $payload): IEntity
     {
         return $this->service->addOrganization($payload);
     }
-}
+}

app/Swagger/schemas.php

@@ -351,3 +351,42 @@ class RSVPUpdateRequestSchema_{
     ]
 )]
 class RSVPAdminAddRequestSchema {}
+
+#[OA\Schema(
+    schema: 'Organization',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', example: 1),
+        new OA\Property(property: 'created', type: 'integer', format: 'int64', example: 1633024800),
+        new OA\Property(property: 'last_edited', type: 'integer', format: 'int64', example: 1633024800),
+        new OA\Property(property: 'name', type: 'string', example: 'OpenStack Foundation'),
+    ]
+)]
+class OrganizationSchema {}
+
+#[OA\Schema(
+    schema: 'PaginatedOrganizationsResponse',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
+        new OA\Schema(
+            properties: [
+                new OA\Property(
+                    property: 'data',
+                    type: 'array',
+                    items: new OA\Items(ref: '#/components/schemas/Organization')
+                )
+            ]
+        )
+    ]
+)]
+class PaginatedOrganizationsResponseSchema {}
+
+#[OA\Schema(
+    schema: 'OrganizationCreateRequest',
+    required: ['name'],
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'name', type: 'string', maxLength: 255, example: 'OpenStack Foundation'),
+    ]
+)]
+class OrganizationCreateRequestSchema {}