From 18ac3076eb3deb49c99cea58ee5ffcd193a793fe Mon Sep 17 00:00:00 2001
From: matiasperrone-exo <matias.perrone@exomindset.co>
Date: Fri, 13 Feb 2026 20:43:36 +0000
Subject: [PATCH 1/3] feat: Add OpenAPI documentation annotations for
 OAuth2UserApiController v1

---
 .../Api/OAuth2/OAuth2UserApiController.php    | 413 ++++++++++++++++++
 app/Swagger/Models/UserInfoResponseSchema.php |  90 ++++
 .../OAuth2UserApiControllerSchemas.php        |  26 ++
 .../Requests/CreateUserRequestSchema.php      |  30 ++
 .../UpdateUserGroupsRequestSchema.php         |  36 ++
 .../Requests/UpdateUserPicRequestSchema.php   |  35 ++
 .../Requests/UpdateUserRequestSchema.php      |  29 ++
 app/Swagger/Requests/UserFieldsSchema.php     | 308 +++++++++++++
 app/Swagger/Security/UsersOAuth2Schema.php    |  32 ++
 9 files changed, 999 insertions(+)
 create mode 100644 app/Swagger/Models/UserInfoResponseSchema.php
 create mode 100644 app/Swagger/OAuth2UserApiControllerSchemas.php
 create mode 100644 app/Swagger/Requests/CreateUserRequestSchema.php
 create mode 100644 app/Swagger/Requests/UpdateUserGroupsRequestSchema.php
 create mode 100644 app/Swagger/Requests/UpdateUserPicRequestSchema.php
 create mode 100644 app/Swagger/Requests/UpdateUserRequestSchema.php
 create mode 100644 app/Swagger/Requests/UserFieldsSchema.php
 create mode 100644 app/Swagger/Security/UsersOAuth2Schema.php

diff --git a/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php b/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
index 20356e1d..e29ad85a 100644
--- a/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
+++ b/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
@@ -52,6 +52,75 @@ final class OAuth2UserApiController extends OAuth2ProtectedController
 
     use RequestProcessor;
 
+    #[OA\Get(
+        path: '/api/v1/users',
+        summary: 'Get all users',
+        operationId: 'getUsers',
+        tags: ['Users'],
+        security: [
+            [
+                'user_oauth2' => [
+                    IUserScopes::ReadAll,
+                ]
+            ],
+        ],
+        parameters: [
+            new OA\Parameter(
+                name: 'page',
+                description: 'Page number',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'integer')
+            ),
+            new OA\Parameter(
+                name: 'per_page',
+                description: 'Items per page (5-100)',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'integer')
+            ),
+            new OA\Parameter(
+                name: 'filter',
+                description: 'Filter (first_name, last_name, email, primary_email)',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
+            new OA\Parameter(
+                name: 'order',
+                description: 'Order',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
+            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/PaginatedUserResponseSchema')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_NOT_FOUND,
+                description: 'Not Found'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_PRECONDITION_FAILED,
+                description: 'Validation Failed'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     protected function getAllSerializerType(): string
     {
         return SerializerRegistry::SerializerType_Private;
@@ -142,6 +211,32 @@ public function __construct
      * Gets User Basic Info
      * @return mixed
      */
+    #[OA\Get(
+        path: '/api/v1/users/me',
+        summary: 'Get current user basic info',
+        operationId: 'getCurrentUser',
+        tags: ['Users'],
+        security: [
+            [
+                'user_oauth2' => [
+                    IUserScopes::Profile,
+                    IUserScopes::Email,
+                    IUserScopes::Address,
+                ]
+            ],
+        ],
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_OK,
+                description: 'OK',
+                content: new OA\JsonContent(ref: '#/components/schemas/User')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     public function me()
     {
         try {
@@ -237,18 +332,194 @@ private function _update($id){
         }
     }
 
+    #[OA\Post(
+        path: '/api/v1/users',
+        summary: 'Create a new user',
+        operationId: 'createUser',
+        tags: ['Users'],
+        security: [
+            [
+                'user_oauth2' => [
+                    IUserScopes::Write,
+                ]
+            ],
+        ],
+        requestBody: new OA\RequestBody(
+            description: 'User data',
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/CreateUserRequest')
+        ),
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_CREATED,
+                description: 'Created',
+                content: new OA\JsonContent(ref: '#/components/schemas/User')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_BAD_REQUEST,
+                description: 'Bad Request'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_NOT_FOUND,
+                description: 'Not Found'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_PRECONDITION_FAILED,
+                description: 'Validation Failed'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     public function create(){
        return $this->_create();
     }
 
+    #[OA\Put(
+        path: '/api/v1/users/me',
+        summary: 'Update current user',
+        operationId: 'updateCurrentUser',
+        tags: ['Users'],
+        security: [
+            [
+                'user_oauth2' => [
+                    IUserScopes::MeWrite,
+                ]
+            ],
+        ],
+        requestBody: new OA\RequestBody(
+            description: 'User data to update',
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/UpdateUserRequest')
+        ),
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_CREATED,
+                description: 'Updated',
+                content: new OA\JsonContent(ref: '#/components/schemas/User')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_BAD_REQUEST,
+                description: 'Bad Request'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_NOT_FOUND,
+                description: 'Not Found'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_PRECONDITION_FAILED,
+                description: 'Validation Failed'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     public function updateMe(){
         return $this->_update($this->resource_server_context->getCurrentUserId());
     }
 
+    #[OA\Put(
+        path: '/api/v1/users/{id}',
+        summary: 'Update a user by ID',
+        operationId: 'updateUser',
+        tags: ['Users'],
+        security: [
+            [
+                'user_oauth2' => [
+                    IUserScopes::Write,
+                ]
+            ],
+        ],
+        parameters: [
+            new OA\Parameter(
+                name: 'id',
+                description: 'User ID',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'integer')
+            ),
+        ],
+        requestBody: new OA\RequestBody(
+            description: 'User data to update',
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/UpdateUserRequest')
+        ),
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_CREATED,
+                description: 'Updated',
+                content: new OA\JsonContent(ref: '#/components/schemas/User')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_BAD_REQUEST,
+                description: 'Bad Request'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_NOT_FOUND,
+                description: 'Not Found'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_PRECONDITION_FAILED,
+                description: 'Validation Failed'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     public function update($id){
        return $this->_update($id);
     }
 
+    #[OA\Put(
+        path: '/api/v1/users/me/pic',
+        summary: 'Update current user profile picture',
+        operationId: 'updateCurrentUserProfilePicture',
+        tags: ['Users'],
+        security: [
+            [
+                'user_oauth2' => [
+                    IUserScopes::MeWrite,
+                ]
+            ],
+        ],
+        requestBody: new OA\RequestBody(
+            description: 'Profile picture file',
+            required: true,
+            content: new OA\MediaType(
+                mediaType: 'multipart/form-data',
+                schema: new OA\Schema(ref: '#/components/schemas/UpdateUserPicRequest')
+            )
+        ),
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_CREATED,
+                description: 'Updated',
+                content: new OA\JsonContent(ref: '#/components/schemas/User')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_FORBIDDEN,
+                description: 'Forbidden'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_NOT_FOUND,
+                description: 'Not Found'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_PRECONDITION_FAILED,
+                description: 'Validation Failed'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     public function updateMyPic(LaravelRequest $request){
         try {
             if (!$this->resource_server_context->getCurrentUserId()) {
@@ -279,6 +550,58 @@ public function updateMyPic(LaravelRequest $request){
         }
     }
 
+    #[OA\Get(
+        path: '/api/v1/users/info',
+        summary: 'Get current user info (OpenID Connect UserInfo)',
+        operationId: 'getUserInfo',
+        tags: ['Users'],
+        security: [
+            [
+                'user_oauth2' => [
+                    IUserScopes::Profile,
+                    IUserScopes::Email,
+                    IUserScopes::Address,
+                ]
+            ],
+        ],
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_OK,
+                description: 'OK',
+                content: new OA\JsonContent(ref: '#/components/schemas/UserInfoResponse')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
+    #[OA\Post(
+        path: '/api/v1/users/info',
+        summary: 'Get current user info (OpenID Connect UserInfo)',
+        operationId: 'getUserInfoPost',
+        tags: ['Users'],
+        security: [
+            [
+                'user_oauth2' => [
+                    IUserScopes::Profile,
+                    IUserScopes::Email,
+                    IUserScopes::Address,
+                ]
+            ],
+        ],
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_OK,
+                description: 'OK',
+                content: new OA\JsonContent(ref: '#/components/schemas/UserInfoResponse')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     public function userInfo()
     {
         try {
@@ -315,6 +638,47 @@ public function userInfo()
      * @param $id
      * @return \Illuminate\Http\JsonResponse|mixed
      */
+    #[OA\Get(
+        path: '/api/v1/users/{id}',
+        summary: 'Get a user by ID',
+        operationId: 'getUserById',
+        tags: ['Users'],
+        security: [
+            [
+                'user_oauth2' => [
+                    IUserScopes::ReadAll,
+                ]
+            ],
+        ],
+        parameters: [
+            new OA\Parameter(
+                name: 'id',
+                description: 'User ID',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'integer')
+            ),
+        ],
+        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_PRECONDITION_FAILED,
+                description: 'Validation Failed'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     public function get($id)
     {
         try {
@@ -408,6 +772,55 @@ public function getV2($id)
      * @param $user_id
      * @return JsonResponse|mixed
      */
+    #[OA\Put(
+        path: '/api/v1/users/{id}/groups',
+        summary: 'Update user group assignments (only for account type "SERVICE")',
+        operationId: 'updateUserGroups',
+        tags: ['Users'],
+        security: [
+            [
+                'user_oauth2' => [
+                    IUserScopes::UserGroupWrite,
+                ]
+            ],
+        ],
+        parameters: [
+            new OA\Parameter(
+                name: 'id',
+                description: 'User ID',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'integer')
+            ),
+        ],
+        requestBody: new OA\RequestBody(
+            description: 'Group IDs to assign',
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/UpdateUserGroupsRequest')
+        ),
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_CREATED,
+                description: 'Updated'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_BAD_REQUEST,
+                description: 'Bad Request'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_NOT_FOUND,
+                description: 'Not Found'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_PRECONDITION_FAILED,
+                description: 'Validation Failed'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     public function updateUserGroups($user_id): mixed
     {
         return $this->processRequest(function() use($user_id) {
diff --git a/app/Swagger/Models/UserInfoResponseSchema.php b/app/Swagger/Models/UserInfoResponseSchema.php
new file mode 100644
index 00000000..3ef3209f
--- /dev/null
+++ b/app/Swagger/Models/UserInfoResponseSchema.php
@@ -0,0 +1,90 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OAuth2\AddressClaim;
+use OAuth2\StandardClaims;
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'UserInfoAddressClaim',
+    title: 'Address Claim',
+    description: 'OpenID Connect Address Claim (RFC 5.1.1)',
+    type: 'object',
+    properties: [
+        new OA\Property(property: AddressClaim::Country, type: 'string', description: 'Country name'),
+        new OA\Property(property: AddressClaim::StreetAddress, type: 'string', description: 'Full street address component'),
+        new OA\Property(property: AddressClaim::Address1, type: 'string', description: 'Address line 1'),
+        new OA\Property(property: AddressClaim::Address2, type: 'string', description: 'Address line 2'),
+        new OA\Property(property: AddressClaim::PostalCode, type: 'string', description: 'Zip code or postal code'),
+        new OA\Property(property: AddressClaim::Region, type: 'string', description: 'State, province, or region'),
+        new OA\Property(property: AddressClaim::Locality, type: 'string', description: 'City or locality'),
+        new OA\Property(property: AddressClaim::Formatted, type: 'string', description: 'Full mailing address, formatted for display'),
+    ]
+)]
+class UserInfoAddressClaimSchema
+{
+}
+
+#[OA\Schema(
+    schema: 'UserInfoResponse',
+    title: 'UserInfo Response',
+    description: 'OpenID Connect UserInfo endpoint response. Claims returned depend on the requested scopes (profile, email, address).',
+    type: 'object',
+    required: [StandardClaims::SubjectIdentifier, 'aud'],
+    properties: [
+        // JWT standard claims
+        new OA\Property(property: StandardClaims::SubjectIdentifier, type: 'string', description: 'Subject identifier for the End-User'),
+        new OA\Property(property: 'aud', type: 'string', description: 'Audience (client ID)'),
+
+        // Profile scope claims
+        new OA\Property(property: StandardClaims::Name, type: 'string', description: 'Full name'),
+        new OA\Property(property: StandardClaims::GivenName, type: 'string', description: 'First name'),
+        new OA\Property(property: StandardClaims::PreferredUserName, type: 'string', description: 'Preferred username'),
+        new OA\Property(property: StandardClaims::FamilyName, type: 'string', description: 'Last name'),
+        new OA\Property(property: StandardClaims::NickName, type: 'string', description: 'Casual name or identifier'),
+        new OA\Property(property: StandardClaims::Picture, type: 'string', format: 'uri', description: 'Profile picture URL'),
+        new OA\Property(property: StandardClaims::Birthdate, type: 'string', description: 'Date of birth'),
+        new OA\Property(property: StandardClaims::Gender, type: 'string', description: 'Gender'),
+        new OA\Property(property: StandardClaims::GenderSpecify, type: 'string', description: 'Gender specification'),
+        new OA\Property(property: StandardClaims::Locale, type: 'string', description: 'Preferred language'),
+        new OA\Property(property: StandardClaims::Bio, type: 'string', description: 'User biography'),
+        new OA\Property(property: StandardClaims::StatementOfInterest, type: 'string', description: 'Statement of interest'),
+        new OA\Property(property: StandardClaims::Irc, type: 'string', description: 'IRC handle'),
+        new OA\Property(property: StandardClaims::GitHubUser, type: 'string', description: 'GitHub username'),
+        new OA\Property(property: StandardClaims::WeChatUser, type: 'string', description: 'WeChat username'),
+        new OA\Property(property: StandardClaims::TwitterName, type: 'string', description: 'Twitter handle'),
+        new OA\Property(property: StandardClaims::LinkedInProfile, type: 'string', description: 'LinkedIn profile URL'),
+        new OA\Property(property: StandardClaims::Company, type: 'string', description: 'Company name'),
+        new OA\Property(property: StandardClaims::JobTitle, type: 'string', description: 'Job title'),
+        new OA\Property(property: StandardClaims::ShowPicture, type: 'boolean', description: 'Show photo in public profile'),
+        new OA\Property(property: StandardClaims::ShowBio, type: 'boolean', description: 'Show bio in public profile'),
+        new OA\Property(property: StandardClaims::ShowSocialMediaInfo, type: 'boolean', description: 'Show social media info in public profile'),
+        new OA\Property(property: StandardClaims::ShowFullName, type: 'boolean', description: 'Show full name in public profile'),
+        new OA\Property(property: StandardClaims::AllowChatWithMe, type: 'boolean', description: 'Allow chat in public profile'),
+        new OA\Property(property: StandardClaims::ShowTelephoneNumber, type: 'boolean', description: 'Show telephone in public profile'),
+        new OA\Property(
+            property: StandardClaims::Groups,
+            type: 'array',
+            items: new OA\Items(ref: '#/components/schemas/Group'),
+            description: 'User groups'
+        ),
+
+        // Email scope claims
+        new OA\Property(property: StandardClaims::Email, type: 'string', format: 'email', description: 'Primary email address'),
+        new OA\Property(property: StandardClaims::SecondEmail, type: 'string', format: 'email', description: 'Secondary email address'),
+        new OA\Property(property: StandardClaims::ThirdEmail, type: 'string', format: 'email', description: 'Tertiary email address'),
+        new OA\Property(property: StandardClaims::EmailVerified, type: 'boolean', description: 'Whether the primary email is verified'),
+        new OA\Property(property: StandardClaims::ShowEmail, type: 'boolean', description: 'Whether to show the email or not'),
+
+        // Address scope claims
+        new OA\Property(
+            property: StandardClaims::Address,
+            ref: '#/components/schemas/UserInfoAddressClaim',
+            description: 'End-User preferred postal address (address scope)'
+        ),
+    ]
+)]
+class UserInfoResponseSchema
+{
+}
diff --git a/app/Swagger/OAuth2UserApiControllerSchemas.php b/app/Swagger/OAuth2UserApiControllerSchemas.php
new file mode 100644
index 00000000..bdbe8cbd
--- /dev/null
+++ b/app/Swagger/OAuth2UserApiControllerSchemas.php
@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'PaginatedUserResponseSchema',
+    type: 'object',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: 'data',
+                    type: 'array',
+                    items: new OA\Items(ref: '#/components/schemas/User')
+                )
+            ]
+        )
+    ]
+)]
+class PaginatedUserResponseSchema
+{
+}
diff --git a/app/Swagger/Requests/CreateUserRequestSchema.php b/app/Swagger/Requests/CreateUserRequestSchema.php
new file mode 100644
index 00000000..5cdfbd44
--- /dev/null
+++ b/app/Swagger/Requests/CreateUserRequestSchema.php
@@ -0,0 +1,30 @@
+<?php namespace App\Swagger\schemas;
+
+/**
+ * Copyright 2025 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'CreateUserRequest',
+    title: 'Create User Request',
+    description: 'Request body for creating a new user. Only email is required, all other fields are optional.',
+    type: 'object',
+    required: ['email'],
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/UserFields')
+    ]
+)]
+class CreateUserRequestSchema
+{
+}
diff --git a/app/Swagger/Requests/UpdateUserGroupsRequestSchema.php b/app/Swagger/Requests/UpdateUserGroupsRequestSchema.php
new file mode 100644
index 00000000..532df538
--- /dev/null
+++ b/app/Swagger/Requests/UpdateUserGroupsRequestSchema.php
@@ -0,0 +1,36 @@
+<?php namespace App\Swagger\schemas;
+
+/**
+ * Copyright 2025 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'UpdateUserGroupsRequest',
+    title: 'Update User Groups Request',
+    description: 'Request body for updating user group assignments',
+    type: 'object',
+    required: ['groups'],
+    properties: [
+        new OA\Property(
+            property: 'groups',
+            type: 'array',
+            items: new OA\Items(type: 'integer'),
+            description: 'Array of group IDs to assign to the user',
+            example: [1, 2, 3]
+        )
+    ]
+)]
+class UpdateUserGroupsRequestSchema
+{
+}
diff --git a/app/Swagger/Requests/UpdateUserPicRequestSchema.php b/app/Swagger/Requests/UpdateUserPicRequestSchema.php
new file mode 100644
index 00000000..875b808a
--- /dev/null
+++ b/app/Swagger/Requests/UpdateUserPicRequestSchema.php
@@ -0,0 +1,35 @@
+<?php namespace App\Swagger\schemas;
+
+/**
+ * Copyright 2025 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'UpdateUserPicRequest',
+    title: 'Update User Profile Picture Request',
+    description: 'Request body for uploading a user profile picture',
+    type: 'object',
+    required: ['file'],
+    properties: [
+        new OA\Property(
+            property: 'file',
+            description: 'Profile picture image file',
+            type: 'string',
+            format: 'binary'
+        ),
+    ]
+)]
+class UpdateUserPicRequestSchema
+{
+}
diff --git a/app/Swagger/Requests/UpdateUserRequestSchema.php b/app/Swagger/Requests/UpdateUserRequestSchema.php
new file mode 100644
index 00000000..0221a417
--- /dev/null
+++ b/app/Swagger/Requests/UpdateUserRequestSchema.php
@@ -0,0 +1,29 @@
+<?php namespace App\Swagger\schemas;
+
+/**
+ * Copyright 2025 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'UpdateUserRequest',
+    title: 'Update User Request',
+    description: 'Request body for updating a user. All fields are optional. Note: groups, email_verified, and active fields are automatically removed from non-admin requests.',
+    type: 'object',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/UserFields')
+    ]
+)]
+class UpdateUserRequestSchema
+{
+}
diff --git a/app/Swagger/Requests/UserFieldsSchema.php b/app/Swagger/Requests/UserFieldsSchema.php
new file mode 100644
index 00000000..11476edf
--- /dev/null
+++ b/app/Swagger/Requests/UserFieldsSchema.php
@@ -0,0 +1,308 @@
+<?php namespace App\Swagger\schemas;
+
+/**
+ * Copyright 2025 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'UserFields',
+    title: 'User Fields',
+    description: 'Common user fields used across user operations',
+    type: 'object',
+    properties: [
+        // Personal Information
+        new OA\Property(
+            property: 'first_name',
+            type: 'string',
+            description: 'User first name',
+            nullable: true,
+            example: 'John'
+        ),
+        new OA\Property(
+            property: 'last_name',
+            type: 'string',
+            description: 'User last name',
+            nullable: true,
+            example: 'Doe'
+        ),
+        new OA\Property(
+            property: 'gender',
+            type: 'string',
+            description: 'User gender',
+            nullable: true,
+            example: 'Male'
+        ),
+        new OA\Property(
+            property: 'gender_specify',
+            type: 'string',
+            description: 'Custom gender specification',
+            nullable: true
+        ),
+        new OA\Property(
+            property: 'birthday',
+            type: 'integer',
+            description: 'Birthday as Unix timestamp (seconds since epoch)',
+            nullable: true,
+            example: 631152000
+        ),
+        new OA\Property(
+            property: 'language',
+            type: 'string',
+            description: 'Preferred language',
+            nullable: true,
+            example: 'en'
+        ),
+
+        // Contact Information
+        new OA\Property(
+            property: 'email',
+            type: 'string',
+            format: 'email',
+            description: 'Primary email address',
+            example: 'john.doe@example.com'
+        ),
+        new OA\Property(
+            property: 'second_email',
+            type: 'string',
+            format: 'email',
+            description: 'Secondary email address',
+            nullable: true,
+            example: 'john.work@example.com'
+        ),
+        new OA\Property(
+            property: 'third_email',
+            type: 'string',
+            format: 'email',
+            description: 'Tertiary email address',
+            nullable: true,
+            example: 'john.alt@example.com'
+        ),
+        new OA\Property(
+            property: 'phone_number',
+            type: 'string',
+            description: 'Phone number',
+            nullable: true,
+            example: '+1-555-0123'
+        ),
+
+        // Address Fields
+        new OA\Property(
+            property: 'address1',
+            type: 'string',
+            description: 'Address line 1',
+            nullable: true,
+            example: '123 Main Street'
+        ),
+        new OA\Property(
+            property: 'address2',
+            type: 'string',
+            description: 'Address line 2',
+            nullable: true,
+            example: 'Apt 4B'
+        ),
+        new OA\Property(
+            property: 'city',
+            type: 'string',
+            description: 'City',
+            nullable: true,
+            example: 'San Francisco'
+        ),
+        new OA\Property(
+            property: 'state',
+            type: 'string',
+            description: 'State or province',
+            nullable: true,
+            example: 'CA'
+        ),
+        new OA\Property(
+            property: 'post_code',
+            type: 'string',
+            description: 'Postal code',
+            nullable: true,
+            example: '94102'
+        ),
+        new OA\Property(
+            property: 'country_iso_code',
+            type: 'string',
+            description: 'ISO 3166-1 alpha-2 country code',
+            nullable: true,
+            example: 'US'
+        ),
+
+        // Professional Information
+        new OA\Property(
+            property: 'company',
+            type: 'string',
+            description: 'Company name',
+            nullable: true,
+            example: 'Acme Corp'
+        ),
+        new OA\Property(
+            property: 'job_title',
+            type: 'string',
+            description: 'Job title (max 200 characters)',
+            nullable: true,
+            maxLength: 200,
+            example: 'Software Engineer'
+        ),
+        new OA\Property(
+            property: 'bio',
+            type: 'string',
+            description: 'User biography (HTML content will be sanitized)',
+            nullable: true,
+            example: 'Passionate developer with 10 years of experience'
+        ),
+        new OA\Property(
+            property: 'statement_of_interest',
+            type: 'string',
+            description: 'Statement of interest (HTML content will be sanitized)',
+            nullable: true,
+            example: 'Interested in cloud computing and open source'
+        ),
+
+        // Social Media
+        new OA\Property(
+            property: 'irc',
+            type: 'string',
+            description: 'IRC nickname',
+            nullable: true,
+            example: 'johndoe'
+        ),
+        new OA\Property(
+            property: 'twitter_name',
+            type: 'string',
+            description: 'Twitter username',
+            nullable: true,
+            example: '@johndoe'
+        ),
+        new OA\Property(
+            property: 'linked_in_profile',
+            type: 'string',
+            description: 'LinkedIn profile URL',
+            nullable: true,
+            example: 'https://linkedin.com/in/johndoe'
+        ),
+        new OA\Property(
+            property: 'github_user',
+            type: 'string',
+            description: 'GitHub username',
+            nullable: true,
+            example: 'johndoe'
+        ),
+        new OA\Property(
+            property: 'wechat_user',
+            type: 'string',
+            description: 'WeChat username',
+            nullable: true,
+            example: 'johndoe'
+        ),
+
+        // Public Profile Settings
+        new OA\Property(
+            property: 'public_profile_show_photo',
+            type: 'boolean',
+            description: 'Show photo in public profile',
+            example: true
+        ),
+        new OA\Property(
+            property: 'public_profile_show_fullname',
+            type: 'boolean',
+            description: 'Show full name in public profile',
+            example: true
+        ),
+        new OA\Property(
+            property: 'public_profile_show_email',
+            type: 'boolean',
+            description: 'Show email in public profile',
+            example: false
+        ),
+        new OA\Property(
+            property: 'public_profile_show_social_media_info',
+            type: 'boolean',
+            description: 'Show social media information in public profile',
+            example: true
+        ),
+        new OA\Property(
+            property: 'public_profile_show_bio',
+            type: 'boolean',
+            description: 'Show biography in public profile',
+            example: true
+        ),
+        new OA\Property(
+            property: 'public_profile_allow_chat_with_me',
+            type: 'boolean',
+            description: 'Allow others to chat with me',
+            example: true
+        ),
+        new OA\Property(
+            property: 'public_profile_show_telephone_number',
+            type: 'boolean',
+            description: 'Show telephone number in public profile',
+            example: false
+        ),
+
+        // Security
+        new OA\Property(
+            property: 'password',
+            type: 'string',
+            description: 'Password (must meet password policy requirements)',
+            example: 'SecureP@ssw0rd'
+        ),
+        new OA\Property(
+            property: 'password_confirmation',
+            type: 'string',
+            description: 'Password confirmation (required when password is provided)',
+            example: 'SecureP@ssw0rd'
+        ),
+        new OA\Property(
+            property: 'current_password',
+            type: 'string',
+            description: 'Current password (required when changing password for non-admin users)',
+            example: 'OldP@ssw0rd'
+        ),
+
+        // Admin Fields (accepted on create; automatically removed on update for non-admin users by curateUpdatePayload)
+        new OA\Property(
+            property: 'groups',
+            type: 'array',
+            items: new OA\Items(type: 'integer'),
+            description: 'Array of group IDs to assign (admin only, requires users/write scope)',
+            example: [1, 2, 3]
+        ),
+        new OA\Property(
+            property: 'email_verified',
+            type: 'boolean',
+            description: 'Email verification status (admin only, requires users/write scope; ignored on update for non-admin users)',
+            nullable: true,
+            example: true
+        ),
+        new OA\Property(
+            property: 'active',
+            type: 'boolean',
+            description: 'Account active status (admin only, requires users/write scope; ignored on update for non-admin users)',
+            nullable: true,
+            example: true
+        ),
+        new OA\Property(
+            property: 'identifier',
+            type: 'string',
+            description: 'User identifier',
+            nullable: true,
+            example: 'user-12345'
+        ),
+    ]
+)]
+class UserFieldsSchema
+{
+}
diff --git a/app/Swagger/Security/UsersOAuth2Schema.php b/app/Swagger/Security/UsersOAuth2Schema.php
new file mode 100644
index 00000000..53f2ceca
--- /dev/null
+++ b/app/Swagger/Security/UsersOAuth2Schema.php
@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use App\libs\OAuth2\IUserScopes;
+use OpenApi\Attributes as OA;
+
+#[
+    OA\SecurityScheme(
+    type: 'oauth2',
+    securityScheme: 'user_oauth2',
+    flows: [
+        new OA\Flow(
+            flow: 'authorizationCode',
+            authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
+            tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+            scopes: [
+                IUserScopes::Profile => 'Read User Profile',
+                IUserScopes::Email => 'Read User Email',
+                IUserScopes::Address => 'Read User Address',
+                IUserScopes::ReadAll => 'Read All Users Data',
+                IUserScopes::MeWrite => 'Write Current User Data',
+                IUserScopes::Write => 'Write Users Data',
+                IUserScopes::UserGroupWrite => 'Write User Group Assignments',
+            ],
+        ),
+    ],
+)
+]
+class UsersOAuth2Schema
+{
+}

From 1901d76561ae871cc803b67df9d464899b098c77 Mon Sep 17 00:00:00 2001
From: matiasperrone-exo <matias.perrone@exomindset.co>
Date: Mon, 16 Mar 2026 19:32:43 +0000
Subject: [PATCH 2/3] chore: Add PR requested changes

---
 .../Api/OAuth2/OAuth2UserApiController.php    | 142 +++++++++---------
 .../OAuth2UserApiControllerSchemas.php        |   2 +-
 app/Swagger/Security/UsersOAuth2Schema.php    |   2 +-
 3 files changed, 71 insertions(+), 75 deletions(-)

diff --git a/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php b/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
index e29ad85a..94b19bc0 100644
--- a/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
+++ b/app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php
@@ -1,4 +1,5 @@
-<?php namespace App\Http\Controllers\Api\OAuth2;
+<?php
+namespace App\Http\Controllers\Api\OAuth2;
 /**
  * Copyright 2015 OpenStack Foundation
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -59,7 +60,7 @@ final class OAuth2UserApiController extends OAuth2ProtectedController
         tags: ['Users'],
         security: [
             [
-                'user_oauth2' => [
+                'OAuth2UserSecurity' => [
                     IUserScopes::ReadAll,
                 ]
             ],
@@ -105,7 +106,7 @@ final class OAuth2UserApiController extends OAuth2ProtectedController
             new OA\Response(
                 response: HttpResponse::HTTP_OK,
                 description: 'OK',
-                content: new OA\JsonContent(ref: '#/components/schemas/PaginatedUserResponseSchema')
+                content: new OA\JsonContent(ref: '#/components/schemas/PaginatedUserResponse')
             ),
             new OA\Response(
                 response: HttpResponse::HTTP_NOT_FOUND,
@@ -197,8 +198,7 @@ public function __construct
         IOpenIdUserService $openid_user_service,
         IClientRepository $client_repository,
         IdTokenBuilder $id_token_builder
-    )
-    {
+    ) {
         parent::__construct($resource_server_context, $log_service);
         $this->repository = $repository;
         $this->user_service = $user_service;
@@ -217,13 +217,9 @@ public function __construct
         operationId: 'getCurrentUser',
         tags: ['Users'],
         security: [
-            [
-                'user_oauth2' => [
-                    IUserScopes::Profile,
-                    IUserScopes::Email,
-                    IUserScopes::Address,
-                ]
-            ],
+            ['OAuth2UserSecurity' => [IUserScopes::Profile]],
+            ['OAuth2UserSecurity' => [IUserScopes::Email]],
+            ['OAuth2UserSecurity' => [IUserScopes::Address]],
         ],
         responses: [
             new OA\Response(
@@ -252,24 +248,27 @@ protected function curateUpdatePayload(array $payload): array
     {
         // remove possible fields that an user can not update
         // from this endpoint
-        if(isset($payload['groups']))
+        if (isset($payload['groups']))
             unset($payload['groups']);
 
-        if(isset($payload['email_verified']))
+        if (isset($payload['email_verified']))
             unset($payload['email_verified']);
 
-        if(isset($payload['active']))
+        if (isset($payload['active']))
             unset($payload['active']);
 
         return HTMLCleaner::cleanData($payload, [
-            'bio', 'statement_of_interest'
+            'bio',
+            'statement_of_interest'
         ]);
     }
 
-      private function _create(){
+    private function _create()
+    {
         try {
 
-            if(!Request::isJson()) return $this->error400();
+            if (!Request::isJson())
+                return $this->error400();
 
             $payload = Request::json()->all();
             // Creates a Validator instance and validates the data.
@@ -282,27 +281,24 @@ private function _create(){
             $user = $this->openid_user_service->create($payload);
 
             return $this->created(SerializerRegistry::getInstance()->getSerializer($user, SerializerRegistry::SerializerType_Private)->serialize());
-        }
-        catch (ValidationException $ex1)
-        {
+        } catch (ValidationException $ex1) {
             Log::warning($ex1);
             return $this->error412($ex1->getMessages());
-        }
-        catch (EntityNotFoundException $ex2)
-        {
+        } catch (EntityNotFoundException $ex2) {
             Log::warning($ex2);
             return $this->error404(['message' => $ex2->getMessage()]);
-        }
-        catch (Exception $ex) {
+        } catch (Exception $ex) {
             Log::error($ex);
             return $this->error500($ex);
         }
     }
 
-    private function _update($id){
+    private function _update($id)
+    {
         try {
 
-            if(!Request::isJson()) return $this->error400();
+            if (!Request::isJson())
+                return $this->error400();
 
             $payload = Request::json()->all();
             // Creates a Validator instance and validates the data.
@@ -315,18 +311,13 @@ private function _update($id){
             $user = $this->openid_user_service->update($id, $this->curateUpdatePayload($payload));
 
             return $this->updated(SerializerRegistry::getInstance()->getSerializer($user, SerializerRegistry::SerializerType_Private)->serialize());
-        }
-        catch (ValidationException $ex1)
-        {
+        } catch (ValidationException $ex1) {
             Log::warning($ex1);
             return $this->error412($ex1->getMessages());
-        }
-        catch (EntityNotFoundException $ex2)
-        {
+        } catch (EntityNotFoundException $ex2) {
             Log::warning($ex2);
             return $this->error404(['message' => $ex2->getMessage()]);
-        }
-        catch (Exception $ex) {
+        } catch (Exception $ex) {
             Log::error($ex);
             return $this->error500($ex);
         }
@@ -339,7 +330,7 @@ private function _update($id){
         tags: ['Users'],
         security: [
             [
-                'user_oauth2' => [
+                'OAuth2UserSecurity' => [
                     IUserScopes::Write,
                 ]
             ],
@@ -373,8 +364,9 @@ private function _update($id){
             ),
         ]
     )]
-    public function create(){
-       return $this->_create();
+    public function create()
+    {
+        return $this->_create();
     }
 
     #[OA\Put(
@@ -384,7 +376,7 @@ public function create(){
         tags: ['Users'],
         security: [
             [
-                'user_oauth2' => [
+                'OAuth2UserSecurity' => [
                     IUserScopes::MeWrite,
                 ]
             ],
@@ -418,7 +410,8 @@ public function create(){
             ),
         ]
     )]
-    public function updateMe(){
+    public function updateMe()
+    {
         return $this->_update($this->resource_server_context->getCurrentUserId());
     }
 
@@ -429,7 +422,7 @@ public function updateMe(){
         tags: ['Users'],
         security: [
             [
-                'user_oauth2' => [
+                'OAuth2UserSecurity' => [
                     IUserScopes::Write,
                 ]
             ],
@@ -472,8 +465,9 @@ public function updateMe(){
             ),
         ]
     )]
-    public function update($id){
-       return $this->_update($id);
+    public function update($id)
+    {
+        return $this->_update($id);
     }
 
     #[OA\Put(
@@ -483,7 +477,7 @@ public function update($id){
         tags: ['Users'],
         security: [
             [
-                'user_oauth2' => [
+                'OAuth2UserSecurity' => [
                     IUserScopes::MeWrite,
                 ]
             ],
@@ -520,31 +514,27 @@ public function update($id){
             ),
         ]
     )]
-    public function updateMyPic(LaravelRequest $request){
+    public function updateMyPic(LaravelRequest $request)
+    {
         try {
             if (!$this->resource_server_context->getCurrentUserId()) {
                 return $this->error403();
             }
 
-            $file = $request->hasFile('file') ? $request->file('file'):null;
-            if(is_null($file)){
+            $file = $request->hasFile('file') ? $request->file('file') : null;
+            if (is_null($file)) {
                 throw new ValidationException('file is not present');
             }
             $user = $this->openid_user_service->updateProfilePhoto($this->resource_server_context->getCurrentUserId(), $file);
 
             return $this->updated(SerializerRegistry::getInstance()->getSerializer($user, SerializerRegistry::SerializerType_Private)->serialize());
-        }
-        catch (ValidationException $ex1)
-        {
+        } catch (ValidationException $ex1) {
             Log::warning($ex1);
             return $this->error412($ex1->getMessages());
-        }
-        catch (EntityNotFoundException $ex2)
-        {
+        } catch (EntityNotFoundException $ex2) {
             Log::warning($ex2);
             return $this->error404(['message' => $ex2->getMessage()]);
-        }
-        catch (Exception $ex) {
+        } catch (Exception $ex) {
             Log::error($ex);
             return $this->error500($ex);
         }
@@ -556,13 +546,9 @@ public function updateMyPic(LaravelRequest $request){
         operationId: 'getUserInfo',
         tags: ['Users'],
         security: [
-            [
-                'user_oauth2' => [
-                    IUserScopes::Profile,
-                    IUserScopes::Email,
-                    IUserScopes::Address,
-                ]
-            ],
+            ['OAuth2UserSecurity' => [IUserScopes::Profile]],
+            ['OAuth2UserSecurity' => [IUserScopes::Email]],
+            ['OAuth2UserSecurity' => [IUserScopes::Address]],
         ],
         responses: [
             new OA\Response(
@@ -583,7 +569,7 @@ public function updateMyPic(LaravelRequest $request){
         tags: ['Users'],
         security: [
             [
-                'user_oauth2' => [
+                'OAuth2UserSecurity' => [
                     IUserScopes::Profile,
                     IUserScopes::Email,
                     IUserScopes::Address,
@@ -645,7 +631,7 @@ public function userInfo()
         tags: ['Users'],
         security: [
             [
-                'user_oauth2' => [
+                'OAuth2UserSecurity' => [
                     IUserScopes::ReadAll,
                 ]
             ],
@@ -710,9 +696,11 @@ public function get($id)
         operationId: 'getUserByIdV2',
         tags: ['Users', 'V2'],
         security: [
-            ['OAuth2UserSecurity' => [
-                IUserScopes::ReadAll,
-            ]],
+            [
+                'OAuth2UserSecurity' => [
+                    IUserScopes::ReadAll,
+                ]
+            ],
         ],
         x: [
             'x-required-client-type' => 'SERVICE',
@@ -755,7 +743,7 @@ public function get($id)
     )]
     public function getV2($id)
     {
-        return $this->processRequest(function() use($id) {
+        return $this->processRequest(function () use ($id) {
             $user = $this->repository->getById(intval($id));
             if (is_null($user)) {
                 throw new EntityNotFoundException();
@@ -774,16 +762,19 @@ public function getV2($id)
      */
     #[OA\Put(
         path: '/api/v1/users/{id}/groups',
-        summary: 'Update user group assignments (only for account type "SERVICE")',
+        summary: 'Update user group assignments',
         operationId: 'updateUserGroups',
         tags: ['Users'],
         security: [
             [
-                'user_oauth2' => [
+                'OAuth2UserSecurity' => [
                     IUserScopes::UserGroupWrite,
                 ]
             ],
         ],
+        x: [
+            'x-required-client-type' => 'SERVICE',
+        ],
         parameters: [
             new OA\Parameter(
                 name: 'id',
@@ -819,12 +810,17 @@ public function getV2($id)
                 response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
                 description: 'Server Error'
             ),
+            new OA\Response(
+                response: HttpResponse::HTTP_FORBIDDEN,
+                description: 'Forbidden - Only service accounts are allowed'
+            ),
         ]
     )]
     public function updateUserGroups($user_id): mixed
     {
-        return $this->processRequest(function() use($user_id) {
-            if(!Request::isJson()) return $this->error400();
+        return $this->processRequest(function () use ($user_id) {
+            if (!Request::isJson())
+                return $this->error400();
 
             $payload = Request::json()->all();
             // Creates a Validator instance and validates the data.
diff --git a/app/Swagger/OAuth2UserApiControllerSchemas.php b/app/Swagger/OAuth2UserApiControllerSchemas.php
index bdbe8cbd..36b9e32d 100644
--- a/app/Swagger/OAuth2UserApiControllerSchemas.php
+++ b/app/Swagger/OAuth2UserApiControllerSchemas.php
@@ -5,7 +5,7 @@
 use OpenApi\Attributes as OA;
 
 #[OA\Schema(
-    schema: 'PaginatedUserResponseSchema',
+    schema: 'PaginatedUserResponse',
     type: 'object',
     allOf: [
         new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
diff --git a/app/Swagger/Security/UsersOAuth2Schema.php b/app/Swagger/Security/UsersOAuth2Schema.php
index 53f2ceca..76536e93 100644
--- a/app/Swagger/Security/UsersOAuth2Schema.php
+++ b/app/Swagger/Security/UsersOAuth2Schema.php
@@ -8,7 +8,7 @@
 #[
     OA\SecurityScheme(
     type: 'oauth2',
-    securityScheme: 'user_oauth2',
+    securityScheme: 'OAuth2UserSecurity',
     flows: [
         new OA\Flow(
             flow: 'authorizationCode',

From b545fb6c1d6b161cbcab894deb0f274491d4b4c3 Mon Sep 17 00:00:00 2001
From: matiasperrone-exo <matias.perrone@exomindset.co>
Date: Mon, 16 Mar 2026 20:34:46 +0000
Subject: [PATCH 3/3] chore: Add PR requested changes

---
 .../OAuth2UserApiControllerSecuritySchema.php | 30 -------------------
 1 file changed, 30 deletions(-)
 delete mode 100644 app/Swagger/Security/OAuth2UserApiControllerSecuritySchema.php

diff --git a/app/Swagger/Security/OAuth2UserApiControllerSecuritySchema.php b/app/Swagger/Security/OAuth2UserApiControllerSecuritySchema.php
deleted file mode 100644
index faa3e459..00000000
--- a/app/Swagger/Security/OAuth2UserApiControllerSecuritySchema.php
+++ /dev/null
@@ -1,30 +0,0 @@
-<?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
-{
-}