feat: Add OpenAPI documentation for OAuth2DisqusSSOApiController v1 (#111)

Author: matiasperrone-exo

app/Http/Controllers/Api/OAuth2/OAuth2DisqusSSOApiController.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 OAuth2DisqusSSOApiController
  * @package App\Http\Controllers\Api\OAuth2
@@ -40,6 +43,49 @@ public function __construct
         $this->service = $service;
     }
 
+    #[OA\Get(
+        path: '/api/v1/sso/disqus/{forum_slug}/profile',
+        operationId: 'getDisqusUserProfile',
+        summary: 'Get Disqus user profile for a forum',
+        security: [['OAuth2DisqusSSOSecurity' => [IUserScopes::SSO]]],
+        tags: ['Disqus 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/DisqusUserProfileSerialized')
+            ),
+            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'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_FORBIDDEN,
+                description: 'Forbidden'
+            ),
+        ]
+    )]
     /**
      * @param string $forum_slug
      * @return \Illuminate\Http\JsonResponse|mixed

app/Swagger/Models/DisqusUserProfileSerializedSchema.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'DisqusUserProfileSerialized',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'auth', type: 'string', description: 'Base64 encoded profile JSON + space + hash + space + timestamp.'),
+        new OA\Property(property: 'public_key', type: 'string', description: 'Public key'),
+    ],
+    description: 'Disqus SSO user profile'
+)]
+class DisqusUserProfileSerializedSchema
+{
+}

app/Swagger/Security/OAuth2DisqusSSOSecuritySchema.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use App\libs\OAuth2\IUserScopes;
+use OpenApi\Attributes as OA;
+
+#[OA\SecurityScheme(
+    securityScheme: 'OAuth2DisqusSSOSecurity',
+    type: 'oauth2',
+    description: 'OAuth2 authentication for Disqus 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 OAuth2DisqusSSOSecuritySchema
+{
+}