feat: Add OpenAPI documentation annotations for OAuth2StreamChatSSOApiController v1 routes (#110)

Author: matiasperrone-exo

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

@@ -11,11 +11,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  **/
+use App\libs\OAuth2\IUserScopes;
 use App\Services\Auth\IStreamChatSSOService;
 use Illuminate\Support\Facades\Log;
 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 +47,50 @@ public function __construct
      * @param string $forum_slug
      * @return \Illuminate\Http\JsonResponse|mixed
      */
+    #[OA\Get(
+        path: '/api/v1/sso/stream-chat/{forum_slug}/profile',
+        operationId: 'getStreamChatUserProfile',
+        summary: 'Get Stream Chat user profile for a forum',
+        description: 'Returns the Stream Chat user profile and authentication token for the given forum. Requires SSO scope.',
+        security: [['OAuth2StreamChatSSOSecurity' => [IUserScopes::SSO]]],
+        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'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_UNAUTHORIZED,
+                description: 'Unauthorized - invalid or missing token'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_FORBIDDEN,
+                description: 'Forbidden - insufficient scope'
+            ),
+        ]
+    )]
     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', format: 'uri', 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,23 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use App\libs\OAuth2\IUserScopes;
+use OpenApi\Attributes as OA;
+
+#[OA\SecurityScheme(
+    securityScheme: 'OAuth2StreamChatSSOSecurity',
+    type: 'oauth2',
+    description: 'OAuth2 authentication for Stream 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 OAuth2StreamChatSSOApiControllerSecuritySchema
+{
+}