From 5ce71f5c73bbebe027c4d0aef02e6fc9e29e857f Mon Sep 17 00:00:00 2001
From: matiasperrone-exo <matias.perrone@exomindset.co>
Date: Tue, 17 Feb 2026 21:32:34 +0000
Subject: [PATCH] feat: Add OpenAPI documentation for
 OAuth2RocketChatSSOApiController v1 api routes

---
 .../OAuth2RocketChatSSOApiController.php      | 43 +++++++++++++++++++
 .../Models/RocketChatUserProfileSchema.php    | 16 +++++++
 ...cketChatSSOApiControllerSecuritySchema.php | 23 ++++++++++
 3 files changed, 82 insertions(+)
 create mode 100644 app/Swagger/Models/RocketChatUserProfileSchema.php
 create mode 100644 app/Swagger/Security/OAuth2RocketChatSSOApiControllerSecuritySchema.php

diff --git a/app/Http/Controllers/Api/OAuth2/OAuth2RocketChatSSOApiController.php b/app/Http/Controllers/Api/OAuth2/OAuth2RocketChatSSOApiController.php
index 8e7d82cb..60d8ad04 100644
--- a/app/Http/Controllers/Api/OAuth2/OAuth2RocketChatSSOApiController.php
+++ b/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
diff --git a/app/Swagger/Models/RocketChatUserProfileSchema.php b/app/Swagger/Models/RocketChatUserProfileSchema.php
new file mode 100644
index 00000000..c5af2f59
--- /dev/null
+++ b/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
+{
+}
diff --git a/app/Swagger/Security/OAuth2RocketChatSSOApiControllerSecuritySchema.php b/app/Swagger/Security/OAuth2RocketChatSSOApiControllerSecuritySchema.php
new file mode 100644
index 00000000..661d1b04
--- /dev/null
+++ b/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
+{
+}
\ No newline at end of file