Feature | Extend Swagger Coverage for controller OAuth2OrganizationsApiController

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,15 @@
  * limitations under the License.
  **/
 
+use App\Security\OrganizationScopes;
 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 +37,37 @@ final class OAuth2OrganizationsApiController extends OAuth2ProtectedController
     private $service;
 
     use ParametrizedGetAll;
+    use AddEntity;
+
+    #[OA\Post(
+        path: '/api/v1/organizations',
+        summary: 'Creates a new organization',
+        operationId: 'createOrganization',
+        security: [
+            [
+                'organizations_oauth2' => [
+                    OrganizationScopes::WriteOrganizationData
+                ]
+            ]
+        ],
+        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: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
+            new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
+            new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
+            new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
+        ]
+    )]
 
     /**
      * OAuth2OrganizationsApiController constructor.
@@ -40,15 +78,74 @@ final class OAuth2OrganizationsApiController extends OAuth2ProtectedController
     public function __construct
     (
         IOrganizationRepository $company_repository,
-        IResourceServerContext  $resource_server_context,
-        IOrganizationService    $service
-    )
-    {
+        IResourceServerContext $resource_server_context,
+        IOrganizationService $service
+    ) {
         parent::__construct($resource_server_context);
         $this->repository = $company_repository;
         $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: [
+            [
+                'organizations_oauth2' => [
+                    OrganizationScopes::ReadOrganizationData,
+                ]
+            ]
+        ],
+        parameters: [
+            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_UNAUTHORIZED, description: "Unauthorized"),
+            new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
+            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->_getAll(
@@ -77,7 +174,6 @@ function () {
         );
     }
 
-    use AddEntity;
 
     /**
      * @inheritDoc

app/Swagger/Security/OrganizationsAuthSchema.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use App\Security\OrganizationScopes;
+use OpenApi\Attributes as OA;
+
+
+#[OA\SecurityScheme(
+    type: 'oauth2',
+    securityScheme: 'organizations_oauth2',
+    flows: [
+        new OA\Flow(
+            authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
+            tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+            flow: 'authorizationCode',
+            scopes: [
+                OrganizationScopes::WriteOrganizationData => 'Write Organization Data',
+                OrganizationScopes::ReadOrganizationData => 'Read Organization Data',
+            ],
+        ),
+    ],
+)
+]
+class OrganizationsAuthSchema
+{
+}