Feat | Add OpenAPI documentation for OAuth2DisqusSSOApiController 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/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,41 @@ 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'
+            ),
+        ]
+    )]
     /**
      * @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/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: 'string of base64 profile JSON + space + hash + space + timestamp. The base64 encoded profile is a JSON stringfied object containing the user profile information: id, username, email, avatar in that order. The hash is the base64 encoded info signed with public/private keys'),
+        new OA\Property(property: 'public_key', type: 'string', description: 'Public key'),
+    ],
+    description: 'Disqus SSO user profile'
+)]
+class DisqusUserProfileSerializedSchema
+{
+}

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: "support@openstack.org"
+    ),
+    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/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
+{
+}

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