Feat | Add OpenAPI documentation for OAuth2GroupApiController

.env.example

@@ -149,3 +149,12 @@ OTEL_TRACES_SAMPLER_PARENT=false
 # OTEL_INSTRUMENTATION_VIEW=true
 # OTEL_INSTRUMENTATION_LIVEWIRE=true
 # OTEL_INSTRUMENTATION_CONSOLE=true
+
+# OpenAPI CONFIG (former Swagger)
+
+L5_SWAGGER_CONST_HOST=${APP_URL}
+L5_SWAGGER_CONST_AUTH_URL='/oauth2/auth'
+L5_SWAGGER_CONST_TOKEN_URL='/oauth2/token'
+# L5_FORMAT_TO_USE_FOR_DOCS=yaml
+L5_SWAGGER_GENERATE_ALWAYS=true # Dev setting
+L5_SWAGGER_OPEN_API_SPEC_VERSION=3.1.2

.gitignore

@@ -15,7 +15,7 @@ Homestead.yaml
 Homestead.json
 .env
 .env.*
-storage/proxies
+storage/*
 /public/assets/jquery-cookie/
 /public/assets/crypto-js/
 /public/assets/bootstrap-tagsinput/

app/Http/Controllers/Api/OAuth2/OAuth2GroupApiController.php

@@ -16,6 +16,8 @@
 use App\libs\Auth\Repositories\IGroupRepository;
 use App\ModelSerializers\SerializerRegistry;
 use OAuth2\IResourceServerContext;
+use OpenApi\Attributes as OA;
+use Symfony\Component\HttpFoundation\Response;
 use Utils\Services\ILogService;
 
 /**
@@ -26,6 +28,54 @@ final class OAuth2GroupApiController extends OAuth2ProtectedController
 {
     use GetAllTrait;
 
+    #[OA\Get(
+        path: '/api/v1/groups',
+        operationId: 'getGroups',
+        summary: 'Get all groups',
+        description: 'Retrieves a paginated list of groups with optional filtering and ordering.',
+        tags: ['Groups'],
+        parameters: [
+            new OA\Parameter(
+                name: 'page',
+                in: 'query',
+                description: 'Page number for pagination',
+                required: false,
+                schema: new OA\Schema(type: 'integer', minimum: 1, default: 1, example: 1)
+            ),
+            new OA\Parameter(
+                name: 'per_page',
+                in: 'query',
+                description: 'Number of items per page',
+                required: false,
+                schema: new OA\Schema(type: 'integer', minimum: 5, maximum: 100, default: 5, example: 10)
+            ),
+            new OA\Parameter(
+                name: 'filter',
+                in: 'query',
+                description: 'Filter criteria. Supported filters: slug== (exact match). Example: filter=slug==administrators',
+                required: false,
+                schema: new OA\Schema(type: 'string', example: 'slug==administrators')
+            ),
+            new OA\Parameter(
+                name: 'order',
+                in: 'query',
+                description: 'Ordering criteria. Supported fields: id, name, slug. Use + for ascending, - for descending. Example: +name or -id',
+                required: false,
+                schema: new OA\Schema(type: 'string', example: '+name')
+            )
+        ],
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: 'Successful response with paginated groups',
+                content: new OA\JsonContent(ref: '#/components/schemas/PaginatedGroupResponseSchema')
+            ),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: 'Not Found'),
+            new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: 'Validation failed'),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: 'Server error')
+        ]
+    )]
+
     /**
      * OAuth2UserApiController constructor.
      * @param IGroupRepository $repository

app/Swagger/GenericSchemas.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: 'PaginateDataSchemaResponse',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'total', type: 'integer', example: 6),
+        new OA\Property(property: 'per_page', type: 'integer', example: 5),
+        new OA\Property(property: 'current_page', type: 'integer', example: 1),
+        new OA\Property(property: 'last_page', type: 'integer', example: 2),
+    ],
+    description: 'Base pagination metadata'
+)]
+class PaginateDataSchemaResponseSchema
+{
+}
+
+#[OA\Schema(
+    schema: 'Base',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', description: 'Unique identifier', example: 1),
+        new OA\Property(property: 'created_at', type: 'integer', description: 'Creation timestamp (epoch)', example: 1609459200),
+        new OA\Property(property: 'updated_at', type: 'integer', description: 'Last update timestamp (epoch)', example: 1609459200),
+    ],
+    description: 'Base serializer fields'
+)]
+class BaseSchema
+{
+}

app/Swagger/Models/GroupSchema.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Swagger\Models;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'Group',
+    type: 'object',
+    description: 'Group API response - serialized representation of a group',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/Base'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(property: 'name', type: 'string', description: 'Group name', example: 'Administrators'),
+                new OA\Property(property: 'slug', type: 'string', description: 'Group slug for URL-friendly identification', example: 'administrators'),
+                new OA\Property(property: 'active', type: 'boolean', description: 'Whether the group is active', example: true),
+                new OA\Property(property: 'default', type: 'boolean', description: 'Whether this is a default group', example: false),
+            ]
+        )
+    ]
+)]
+class GroupSchema {}

app/Swagger/OAuth2GroupApiControllerSchemas.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Swagger;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'PaginatedGroupResponseSchema',
+    type: 'object',
+    description: 'Paginated list of groups',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: 'data',
+                    type: 'array',
+                    description: 'Array of group objects',
+                    items: new OA\Items(ref: '#/components/schemas/Group')
+                )
+            ]
+        )
+    ]
+)]
+class PaginatedGroupResponseSchemaSchema {}

app/Swagger/OpenApiInfo.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Swagger;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Info(
+    version: "1.0.0",
+    title: "OpenStackID API",
+    description: "OpenStackID IDP API Documentation - OAuth2, OpenID Connect, and User Management",
+    contact: new OA\Contact(
+        name: "OpenStack Foundation",
+        email: "support@openstack.org"
+    ),
+    license: new OA\License(
+        name: "Apache 2.0",
+        url: "http://www.apache.org/licenses/LICENSE-2.0"
+    )
+)]
+#[OA\Server(
+    url: L5_SWAGGER_CONST_HOST,
+    description: "IDP API Server"
+)]
+class OpenApiInfo
+{
+}

app/Swagger/Security/OAuth2GroupApiControllerSecuritySchema.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use App\libs\OAuth2\IGroupScopes;
+use OpenApi\Attributes as OA;
+
+#[OA\SecurityScheme(
+    securityScheme: 'OAuth2GroupsSecurity',
+    type: 'oauth2',
+    description: 'OAuth2 authentication for Group endpoints',
+    flows: [
+        new OA\Flow(
+            flow: 'authorizationCode',
+            authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
+            tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+            scopes: [IGroupScopes::ReadAll => 'Read all groups']
+        ),
+    ]
+)]
+class OAuth2GroupApiControllerSecuritySchema
+{
+}

composer.json

@@ -24,6 +24,7 @@
     "ext-pdo": "*",
     "beberlei/doctrineextensions": "1.5.0",
     "behat/transliterator": "1.5.0",
+    "darkaonline/l5-swagger": "^9.0",
     "ezyang/htmlpurifier": "v4.17.0",
     "firebase/php-jwt": "6.11.1",
     "get-stream/stream-chat": "^3.10.0",
@@ -59,7 +60,8 @@
     "socialiteproviders/okta": "^4.5.0",
     "socialiteproviders/zoho": "^4.1",
     "sokil/php-isocodes": "^3.0",
-    "vladimir-yuldashev/laravel-queue-rabbitmq": "v14.2.0"
+    "vladimir-yuldashev/laravel-queue-rabbitmq": "v14.2.0",
+    "zircote/swagger-php": "^5.8"
   },
   "require-dev": {
     "fakerphp/faker": "^1.23",