From 2c37852cb473ab3360e5299b048155586599d0e4 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] feat: Add OpenAPI documentation annotations for
 OAuth2UserApiController v1

---
 .../Api/OAuth2/OAuth2UserApiController.php    | 416 ++++++++++++++++++
 app/Swagger/Models/BaseUserSchema.php         |  26 ++
 app/Swagger/Models/GroupSchema.php            |  27 ++
 app/Swagger/Models/UserInfoResponseSchema.php |  90 ++++
 app/Swagger/Models/UserSchema.php             |  64 +++
 .../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 ++
 12 files changed, 1119 insertions(+)
 create mode 100644 app/Swagger/Models/BaseUserSchema.php
 create mode 100644 app/Swagger/Models/GroupSchema.php
 create mode 100644 app/Swagger/Models/UserInfoResponseSchema.php
 create mode 100644 app/Swagger/Models/UserSchema.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 fd0b744f..d8fee494 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
@@ -49,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;
@@ -139,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 {
@@ -234,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()) {
@@ -276,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 {
@@ -312,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 {
@@ -355,6 +722,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/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/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/Models/UserSchema.php b/app/Swagger/Models/UserSchema.php
new file mode 100644
index 00000000..85e90651
--- /dev/null
+++ b/app/Swagger/Models/UserSchema.php
@@ -0,0 +1,64 @@
+<?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(ref: '#/components/schemas/Group'),
+                    description: 'User groups (expandable with expand=groups)'
+                ),
+            ]
+        )
+    ]
+)]
+class UserSchema
+{
+}
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
+{
+}