feat: Add OpenAPI documentation annotations for OAuth2StreamChatSSOApiController

Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>

Author: matiasperrone-exo

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

@@ -16,6 +16,8 @@
 use models\exceptions\EntityNotFoundException;
 use models\exceptions\ValidationException;
 use OAuth2\IResourceServerContext;
+use OpenApi\Attributes as OA;
+use Symfony\Component\HttpFoundation\Response as HttpResponse;
 use Utils\Services\ILogService;
 /**
  * Class OAuth2StreamChatSSOApiController
@@ -44,6 +46,40 @@ public function __construct
      * @param string $forum_slug
      * @return \Illuminate\Http\JsonResponse|mixed
      */
+    #[OA\Get(
+        path: '/api/v1/sso/stream-chat/{forum_slug}/profile',
+        summary: 'Get Stream Chat user profile for a forum',
+        security: [['OAuth2StreamChatSSOSecurity' => []]],
+        tags: ['Stream 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',
+                content: new OA\JsonContent(ref: '#/components/schemas/StreamChatUserProfile')
+            ),
+            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'
+            ),
+        ]
+    )]
     public function getUserProfile(string $forum_slug){
         try{
             $profile = $this->service->getUserProfile($forum_slug);

app/Swagger/Models/StreamChatUserProfileSchema.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'StreamChatUserProfile',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'string', description: 'User ID'),
+        new OA\Property(property: 'name', type: 'string', description: 'Display name'),
+        new OA\Property(property: 'image', type: 'string', description: 'Avatar URL'),
+        new OA\Property(property: 'token', type: 'string', description: 'Stream Chat JWT token'),
+        new OA\Property(property: 'api_key', type: 'string', description: 'Stream Chat API key'),
+        new OA\Property(property: 'local_role', type: 'string', description: 'User role in the forum'),
+    ],
+    description: 'Stream Chat SSO user profile'
+)]
+class StreamChatUserProfileSchema
+{
+}

app/Swagger/Security/OAuth2StreamChatSSOApiControllerSecuritySchema.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\SecurityScheme(
+    securityScheme: 'OAuth2StreamChatSSOSecurity',
+    type: 'http',
+    description: 'OAuth2 Bearer token for Stream Chat SSO endpoints',
+    scheme: 'bearer',
+    bearerFormat: 'JWT'
+)]
+class OAuth2StreamChatSSOApiControllerSecuritySchema
+{
+}