Feature | Add OpenAPI documentation controller OAuth2UserApiController

.env.example

@@ -149,3 +149,12 @@ OTEL_TRACES_SAMPLER_PARENT=false
 # OTEL_INSTRUMENTATION_VIEW=true
 # OTEL_INSTRUMENTATION_LIVEWIRE=true
 # OTEL_INSTRUMENTATION_CONSOLE=true
+
+# OpenAPI CONFIG (former Swagger)
+
+L5_SWAGGER_CONST_HOST=${APP_URL}
+L5_SWAGGER_CONST_AUTH_URL=${IDP_AUTHORIZATION_ENDPOINT}
+L5_SWAGGER_CONST_TOKEN_URL=${IDP_TOKEN_ENDPOINT}
+# L5_FORMAT_TO_USE_FOR_DOCS=yaml
+L5_SWAGGER_GENERATE_ALWAYS=true # Dev setting
+L5_SWAGGER_OPEN_API_SPEC_VERSION=3.1.2

.gitignore

@@ -15,7 +15,7 @@ Homestead.yaml
 Homestead.json
 .env
 .env.*
-storage/proxies
+storage/*
 /public/assets/jquery-cookie/
 /public/assets/crypto-js/
 /public/assets/bootstrap-tagsinput/

app/Http/Controllers/Api/OAuth2/OAuth2UserApiController.php

@@ -37,8 +37,11 @@
 use OAuth2\ResourceServer\IUserService;
 use Utils\Http\HttpContentType;
 use Utils\Services\ILogService;
+use App\libs\OAuth2\IUserScopes;
 use Exception;
+use OpenApi\Attributes as OA;
 use OpenId\Services\IUserService as IOpenIdUserService;
+use Symfony\Component\HttpFoundation\Response as HttpResponse;
 /**
  * Class OAuth2UserApiController
  * @package App\Http\Controllers\Api\OAuth2
@@ -336,6 +339,48 @@ public function get($id)
      * @param $id
      * @return \Illuminate\Http\JsonResponse|mixed
      */
+    #[OA\Get(
+        path: '/api/v2/users/{id}',
+        summary: 'Get a user by ID',
+        operationId: 'getUserByIdV2',
+        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')
+            ),
+            new OA\Parameter(
+                name: 'expand',
+                description: 'Expand relations: groups',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_OK,
+                description: 'OK',
+                content: new OA\JsonContent(ref: '#/components/schemas/User')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_NOT_FOUND,
+                description: 'Not Found'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     public function getV2($id)
     {
         return $this->processRequest(function() use($id) {

app/Swagger/GenericSchemas.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\SecurityScheme(
+    securityScheme: "bearerAuth",
+    type: "http",
+    scheme: "bearer",
+    bearerFormat: "JWT"
+)]
+class BearerAuthSchema
+{
+}
+
+#[OA\Schema(
+    schema: 'PaginateDataSchemaResponse',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'total', type: 'integer', example: 6),
+        new OA\Property(property: 'per_page', type: 'integer', example: 5),
+        new OA\Property(property: 'current_page', type: 'integer', example: 1),
+        new OA\Property(property: 'last_page', type: 'integer', example: 2),
+    ],
+    description: 'Base pagination metadata'
+)]
+class PaginateDataSchemaResponseSchema
+{
+}
+
+#[OA\Schema(
+    schema: 'Base',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', description: 'Unique identifier', example: 1),
+        new OA\Property(property: 'created_at', type: 'integer', description: 'Creation timestamp (epoch)', example: 1609459200),
+        new OA\Property(property: 'updated_at', type: 'integer', description: 'Last update timestamp (epoch)', example: 1609459200),
+    ],
+    description: 'Base serializer fields'
+)]
+class BaseSchema
+{
+}

app/Swagger/Models/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
+{
+}

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
+{
+}

app/Swagger/Models/UserSchema.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'User',
+    title: 'User',
+    description: 'User serialized representation (private)',
+    type: 'object',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/BaseUser'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(property: 'email', type: 'string', format: 'email', description: 'Primary email address'),
+                new OA\Property(property: 'identifier', type: 'string', description: 'User unique identifier string'),
+                new OA\Property(property: 'email_verified', type: 'boolean', description: 'Whether the primary email is verified'),
+                new OA\Property(property: 'bio', type: 'string', nullable: true, description: 'User biography'),
+                new OA\Property(property: 'address1', type: 'string', description: 'Address line 1'),
+                new OA\Property(property: 'address2', type: 'string', nullable: true, description: 'Address line 2'),
+                new OA\Property(property: 'city', type: 'string', description: 'City'),
+                new OA\Property(property: 'state', type: 'string', description: 'State or province'),
+                new OA\Property(property: 'post_code', type: 'string', description: 'Postal code'),
+                new OA\Property(property: 'country_iso_code', type: 'string', description: 'ISO country code'),
+                new OA\Property(property: 'second_email', type: 'string', format: 'email', nullable: true, description: 'Secondary email address'),
+                new OA\Property(property: 'third_email', type: 'string', format: 'email', nullable: true, description: 'Tertiary email address'),
+                new OA\Property(property: 'gender', type: 'string', nullable: true, description: 'Gender'),
+                new OA\Property(property: 'gender_specify', type: 'string', nullable: true, description: 'Gender specification'),
+                new OA\Property(property: 'statement_of_interest', type: 'string', nullable: true, description: 'Statement of interest'),
+                new OA\Property(property: 'irc', type: 'string', nullable: true, description: 'IRC handle'),
+                new OA\Property(property: 'linked_in_profile', type: 'string', nullable: true, description: 'LinkedIn profile URL'),
+                new OA\Property(property: 'github_user', type: 'string', nullable: true, description: 'GitHub username'),
+                new OA\Property(property: 'wechat_user', type: 'string', nullable: true, description: 'WeChat username'),
+                new OA\Property(property: 'twitter_name', type: 'string', nullable: true, description: 'Twitter handle'),
+                new OA\Property(property: 'language', type: 'string', nullable: true, description: 'Preferred language'),
+                new OA\Property(property: 'birthday', type: 'integer', nullable: true, description: 'Date of birth (epoch)'),
+                new OA\Property(property: 'phone_number', type: 'string', nullable: true, description: 'Phone number'),
+                new OA\Property(property: 'company', type: 'string', nullable: true, description: 'Company name'),
+                new OA\Property(property: 'job_title', type: 'string', nullable: true, description: 'Job title'),
+                new OA\Property(property: 'spam_type', type: 'string', description: 'Spam classification', enum: ['None', 'Spam', 'Ham']),
+                new OA\Property(property: 'last_login_date', type: 'integer', nullable: true, description: 'Last login date (epoch)'),
+                new OA\Property(property: 'active', type: 'boolean', description: 'Whether the user account is active'),
+                new OA\Property(property: 'public_profile_show_photo', type: 'boolean', description: 'Show photo in public profile'),
+                new OA\Property(property: 'public_profile_show_fullname', type: 'boolean', description: 'Show full name in public profile'),
+                new OA\Property(property: 'public_profile_show_email', type: 'boolean', description: 'Show email in public profile'),
+                new OA\Property(property: 'public_profile_show_social_media_info', type: 'boolean', description: 'Show social media info in public profile'),
+                new OA\Property(property: 'public_profile_show_bio', type: 'boolean', description: 'Show bio in public profile'),
+                new OA\Property(property: 'public_profile_allow_chat_with_me', type: 'boolean', description: 'Allow chat in public profile'),
+                new OA\Property(property: 'public_profile_show_telephone_number', type: 'boolean', description: 'Show telephone in public profile'),
+                new OA\Property(
+                    property: 'groups',
+                    type: 'array',
+                    items: new OA\Items(oneOf: [
+                        new OA\Schema(type: 'string', description: 'Group slug (when not expanded)'),
+                        new OA\Schema(ref: '#/components/schemas/Group', description:'Group object (when expanded)'),
+                    ]),
+                    description: 'User groups (expandable with expand=groups)'
+                ),
+            ]
+        )
+    ]
+)]
+class UserSchema
+{
+}