Feat | Add OpenAPI documentation for OAuth2RocketChatSSOApiController v1

.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/OAuth2RocketChatSSOApiController.php

@@ -17,6 +17,9 @@
 use models\exceptions\ValidationException;
 use OAuth2\IResourceServerContext;
 use Utils\Services\ILogService;
+use App\libs\OAuth2\IUserScopes;
+use OpenApi\Attributes as OA;
+use Symfony\Component\HttpFoundation\Response as HttpResponse;
 /**
  * Class OAuth2RocketChatSSOApiController
  * @package App\Http\Controllers\Api\OAuth2
@@ -39,6 +42,46 @@ public function __construct
         $this->service = $service;
     }
 
+
+    #[OA\Get(
+        path: '/api/v1/sso/rocket-chat/{forum_slug}/profile',
+        operationId: 'getRocketChatUserProfile',
+        summary: 'Get Rocket Chat user profile for a forum.',
+        description: 'Returns Rocket Chat user profile data for the authenticated user in the context of the specified forum. The content of the response is defined by "data" portion of the Rocket Chat login endpoint response structure',
+        security: [['OAuth2RocketChatSSOSecurity' => [IUserScopes::SSO]]],
+        tags: ['Rocket Chat SSO'],
+        parameters: [
+            new OA\Parameter(
+                name: 'forum_slug',
+                description: 'Forum slug',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'string')
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_OK,
+                description: 'OK, returns Rocket Chat user profile data on login success',
+                content: new OA\JsonContent(
+                    // The content of the response is defined by "data" portion of
+                    // the Rocket Chat login endpoint response structure
+                )
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_NOT_FOUND,
+                description: 'Not Found'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_PRECONDITION_FAILED,
+                description: 'Validation Error'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     /**
      * @param string $forum_slug
      * @return \Illuminate\Http\JsonResponse|mixed

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/RocketChatUserProfileSchema.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'RocketChatUserProfile',
+    type: 'object',
+    properties: [
+    ],
+    description: 'Rocket Chat SSO user profile'
+)]
+class RocketChatUserProfileSchema
+{
+}

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: "[email protected]"
+    ),
+    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/OAuth2RocketChatSSOApiControllerSecuritySchema.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use App\libs\OAuth2\IUserScopes;
+use OpenApi\Attributes as OA;
+
+#[OA\SecurityScheme(
+    securityScheme: 'OAuth2RocketChatSSOSecurity',
+    type: 'oauth2',
+    description: 'OAuth2 authentication for Rocket Chat SSO endpoints',
+    flows: [
+        new OA\Flow(
+            flow: 'authorizationCode',
+            authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
+            tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+            scopes: [IUserScopes::SSO => 'Single Sign-On access']
+        ),
+    ]
+)]
+class OAuth2RocketChatSSOApiControllerSecuritySchema
+{
+}

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",