From 089de6d82ff524e274f7e8a4c38996487483a3ce Mon Sep 17 00:00:00 2001
From: matiasperrone-exo <matias.perrone@exomindset.co>
Date: Fri, 13 Feb 2026 21:49:22 +0000
Subject: [PATCH] feat: Add OpenAPI documentation on controller
 OAuth2UserApiController v2 routes

---
 .../Api/OAuth2/OAuth2UserApiController.php    | 46 +++++++++++++
 app/Swagger/Models/BaseUserSchema.php         | 26 +++++++
 app/Swagger/Models/GroupSchema.php            | 27 ++++++++
 app/Swagger/Models/UserSchema.php             | 67 +++++++++++++++++++
 .../OAuth2UserApiControllerSecuritySchema.php | 30 +++++++++
 5 files changed, 196 insertions(+)
 create mode 100644 app/Swagger/Models/BaseUserSchema.php
 create mode 100644 app/Swagger/Models/GroupSchema.php
 create mode 100644 app/Swagger/Models/UserSchema.php
 create mode 100644 app/Swagger/Security/OAuth2UserApiControllerSecuritySchema.php

diff --git a/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php b/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
index fd0b744f..3a2b27d6 100644
--- a/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
+++ b/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
@@ -37,8 +37,11 @@
 use OAuth2\ResourceServer\IUserService;
 use Utils\Http\HttpContentType;
 use Utils\Services\ILogService;
+use App\libs\OAuth2\IUserScopes;
 use Exception;
+use OpenApi\Attributes as OA;
 use OpenId\Services\IUserService as IOpenIdUserService;
+use Symfony\Component\HttpFoundation\Response as HttpResponse;
 /**
  * Class OAuth2UserApiController
  * @package App\Http\Controllers\Api\OAuth2
@@ -336,6 +339,49 @@ public function get($id)
      * @param $id
      * @return \Illuminate\Http\JsonResponse|mixed
      */
+    #[OA\Get(
+        path: '/api/v2/users/{id}',
+        summary: 'Get a user by ID',
+        description: 'Get a user by ID (only for accounts of type "SERVICE")',
+        operationId: 'getUserByIdV2',
+        tags: ['Users'],
+        security: [
+            ['OAuth2UserSecurity' => [
+                IUserScopes::ReadAll,
+            ]],
+        ],
+        parameters: [
+            new OA\Parameter(
+                name: 'id',
+                description: 'User ID',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'integer')
+            ),
+            new OA\Parameter(
+                name: 'expand',
+                description: 'Expand relations: groups',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_OK,
+                description: 'OK',
+                content: new OA\JsonContent(ref: '#/components/schemas/User')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_NOT_FOUND,
+                description: 'Not Found'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     public function getV2($id)
     {
         return $this->processRequest(function() use($id) {
diff --git a/app/Swagger/Models/BaseUserSchema.php b/app/Swagger/Models/BaseUserSchema.php
new file mode 100644
index 00000000..3122e1e2
--- /dev/null
+++ b/app/Swagger/Models/BaseUserSchema.php
@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'BaseUser',
+    title: 'Base User',
+    description: 'Base User serialized representation',
+    type: 'object',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/Base'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(property: 'first_name', type: 'string', description: 'First name', example: 'John'),
+                new OA\Property(property: 'last_name', type: 'string', description: 'Last name', example: 'Doe'),
+                new OA\Property(property: 'pic', type: 'string', format: 'uri', description: 'Profile picture URL'),
+            ]
+        )
+    ]
+)]
+class BaseUserSchema
+{
+}
diff --git a/app/Swagger/Models/GroupSchema.php b/app/Swagger/Models/GroupSchema.php
new file mode 100644
index 00000000..f9ee19a9
--- /dev/null
+++ b/app/Swagger/Models/GroupSchema.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'Group',
+    title: 'Group',
+    description: 'Group serialized representation',
+    type: 'object',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/Base'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(property: 'name', type: 'string', description: 'Group name'),
+                new OA\Property(property: 'slug', type: 'string', description: 'Group slug'),
+                new OA\Property(property: 'active', type: 'boolean', description: 'Whether the group is active'),
+                new OA\Property(property: 'default', type: 'boolean', description: 'Whether the group is a default group'),
+            ]
+        )
+    ]
+)]
+class GroupSchema
+{
+}
diff --git a/app/Swagger/Models/UserSchema.php b/app/Swagger/Models/UserSchema.php
new file mode 100644
index 00000000..8a50e9f5
--- /dev/null
+++ b/app/Swagger/Models/UserSchema.php
@@ -0,0 +1,67 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'User',
+    title: 'User',
+    description: 'User serialized representation (private)',
+    type: 'object',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/BaseUser'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(property: 'email', type: 'string', format: 'email', description: 'Primary email address'),
+                new OA\Property(property: 'identifier', type: 'string', description: 'User unique identifier string'),
+                new OA\Property(property: 'email_verified', type: 'boolean', description: 'Whether the primary email is verified'),
+                new OA\Property(property: 'bio', type: 'string', nullable: true, description: 'User biography'),
+                new OA\Property(property: 'address1', type: 'string', description: 'Address line 1'),
+                new OA\Property(property: 'address2', type: 'string', nullable: true, description: 'Address line 2'),
+                new OA\Property(property: 'city', type: 'string', description: 'City'),
+                new OA\Property(property: 'state', type: 'string', description: 'State or province'),
+                new OA\Property(property: 'post_code', type: 'string', description: 'Postal code'),
+                new OA\Property(property: 'country_iso_code', type: 'string', description: 'ISO country code'),
+                new OA\Property(property: 'second_email', type: 'string', format: 'email', nullable: true, description: 'Secondary email address'),
+                new OA\Property(property: 'third_email', type: 'string', format: 'email', nullable: true, description: 'Tertiary email address'),
+                new OA\Property(property: 'gender', type: 'string', nullable: true, description: 'Gender'),
+                new OA\Property(property: 'gender_specify', type: 'string', nullable: true, description: 'Gender specification'),
+                new OA\Property(property: 'statement_of_interest', type: 'string', nullable: true, description: 'Statement of interest'),
+                new OA\Property(property: 'irc', type: 'string', nullable: true, description: 'IRC handle'),
+                new OA\Property(property: 'linked_in_profile', type: 'string', nullable: true, description: 'LinkedIn profile URL'),
+                new OA\Property(property: 'github_user', type: 'string', nullable: true, description: 'GitHub username'),
+                new OA\Property(property: 'wechat_user', type: 'string', nullable: true, description: 'WeChat username'),
+                new OA\Property(property: 'twitter_name', type: 'string', nullable: true, description: 'Twitter handle'),
+                new OA\Property(property: 'language', type: 'string', nullable: true, description: 'Preferred language'),
+                new OA\Property(property: 'birthday', type: 'integer', nullable: true, description: 'Date of birth (epoch)'),
+                new OA\Property(property: 'phone_number', type: 'string', nullable: true, description: 'Phone number'),
+                new OA\Property(property: 'company', type: 'string', nullable: true, description: 'Company name'),
+                new OA\Property(property: 'job_title', type: 'string', nullable: true, description: 'Job title'),
+                new OA\Property(property: 'spam_type', type: 'string', description: 'Spam classification', enum: ['None', 'Spam', 'Ham']),
+                new OA\Property(property: 'last_login_date', type: 'integer', nullable: true, description: 'Last login date (epoch)'),
+                new OA\Property(property: 'active', type: 'boolean', description: 'Whether the user account is active'),
+                new OA\Property(property: 'public_profile_show_photo', type: 'boolean', description: 'Show photo in public profile'),
+                new OA\Property(property: 'public_profile_show_fullname', type: 'boolean', description: 'Show full name in public profile'),
+                new OA\Property(property: 'public_profile_show_email', type: 'boolean', description: 'Show email in public profile'),
+                new OA\Property(property: 'public_profile_show_social_media_info', type: 'boolean', description: 'Show social media info in public profile'),
+                new OA\Property(property: 'public_profile_show_bio', type: 'boolean', description: 'Show bio in public profile'),
+                new OA\Property(property: 'public_profile_allow_chat_with_me', type: 'boolean', description: 'Allow chat in public profile'),
+                new OA\Property(property: 'public_profile_show_telephone_number', type: 'boolean', description: 'Show telephone in public profile'),
+                new OA\Property(
+                    property: 'groups',
+                    type: 'array',
+                    items: new OA\Items(oneOf: [
+                        new OA\Schema(type: 'string', description: 'Group slug (when not expanded)'),
+                        new OA\Schema(ref: '#/components/schemas/Group', description:'Group object (when expanded)'),
+                    ]),
+                    description: 'User groups (expandable with expand=groups)'
+                ),
+            ]
+        )
+    ]
+)]
+class UserSchema
+{
+}
diff --git a/app/Swagger/Security/OAuth2UserApiControllerSecuritySchema.php b/app/Swagger/Security/OAuth2UserApiControllerSecuritySchema.php
new file mode 100644
index 00000000..faa3e459
--- /dev/null
+++ b/app/Swagger/Security/OAuth2UserApiControllerSecuritySchema.php
@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use App\libs\OAuth2\IUserScopes;
+use OpenApi\Attributes as OA;
+
+#[
+    OA\SecurityScheme(
+    type: 'oauth2',
+    securityScheme: 'OAuth2UserSecurity',
+    description: 'OAuth2 security scheme for user-related API endpoints',
+    flows: [
+        new OA\Flow(
+            flow: 'authorizationCode',
+            authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
+            tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+            scopes: [
+                IUserScopes::ReadAll => 'Read All Users Data',
+                IUserScopes::MeWrite => 'Write current user data',
+                IUserScopes::Write => 'Write Users Data',
+                IUserScopes::UserGroupWrite => 'Manage User Group assignments',
+            ],
+        ),
+    ],
+)
+]
+class OAuth2UserApiControllerSecuritySchema
+{
+}