Feat | Add OpenAPI documentation for OAuth2UserRegistrationRequestApiController

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

@@ -14,6 +14,7 @@
 
 use App\Http\Controllers\GetAllTrait;
 use App\libs\Auth\Repositories\IUserRegistrationRequestRepository;
+use App\libs\OAuth2\IUserScopes;
 use App\ModelSerializers\SerializerRegistry;
 use App\Services\Auth\IUserService;
 use Illuminate\Support\Facades\Log;
@@ -22,6 +23,8 @@
 use models\exceptions\EntityNotFoundException;
 use models\exceptions\ValidationException;
 use OAuth2\IResourceServerContext;
+use OpenApi\Attributes as OA;
+use Symfony\Component\HttpFoundation\Response as HttpResponse;
 use Utils\Services\ILogService;
 /**
  * Class OAuth2UserRegistrationRequestApiController
@@ -43,6 +46,58 @@ final class OAuth2UserRegistrationRequestApiController extends OAuth2ProtectedCo
      * @param IResourceServerContext $resource_server_context
      * @param ILogService $log_service
      */
+    #[OA\Get(
+        path: '/api/v1/user-registration-requests',
+        operationId: 'getUserRegistrationRequests',
+        summary: 'Get all user registration requests',
+        security: [['OAuth2UserRegistrationRequestApi' => [IUserScopes::Registration]]],
+        tags: ['User Registration Requests'],
+        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',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'integer')
+            ),
+            new OA\Parameter(
+                name: 'filter',
+                description: 'Filter criteria (first_name, last_name, email, is_redeemed) ("=@" starts with, "==" exact match)',
+                in: 'query',
+                required: false,
+                schema: new OA\Schema(type: 'string')
+            ),
+            new OA\Parameter(
+                name: 'order',
+                description: 'Order criteria (id)',
+                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/PaginatedUserRegistrationRequestResponse')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_PRECONDITION_FAILED,
+                description: 'Precondition Failed'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+                description: 'Server Error'
+            ),
+        ]
+    )]
     public function __construct
     (
         IUserRegistrationRequestRepository  $repository,
@@ -97,6 +152,41 @@ protected function getFilterValidatorRules(): array
     /**
      * @return \Illuminate\Http\JsonResponse|mixed
      */
+    #[OA\Post(
+        path: '/api/v1/user-registration-requests',
+        operationId: 'createUserRegistrationRequest',
+        summary: 'Create a user registration request',
+        security: [['OAuth2UserRegistrationRequestApi' => [IUserScopes::Registration]]],
+        tags: ['User Registration Requests'],
+        requestBody: new OA\RequestBody(
+            description: 'User registration request data',
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/CreateUserRegistrationRequestRequest')
+        ),
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_CREATED,
+                description: 'Created',
+                content: new OA\JsonContent(ref: '#/components/schemas/UserRegistrationRequest')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_BAD_REQUEST,
+                description: 'Bad Request'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_PRECONDITION_FAILED,
+                description: 'Precondition Failed'
+            ),
+            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 register(){
         try {
 
@@ -148,6 +238,50 @@ public function register(){
      * @param $id
      * @return \Illuminate\Http\JsonResponse|mixed
      */
+    #[OA\Put(
+        path: '/api/v1/user-registration-requests/{id}',
+        operationId: 'updateUserRegistrationRequest',
+        summary: 'Update a user registration request',
+        security: [['OAuth2UserRegistrationRequestApi' => [IUserScopes::Registration]]],
+        tags: ['User Registration Requests'],
+        parameters: [
+            new OA\Parameter(
+                name: 'id',
+                description: 'Registration request ID',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'integer')
+            ),
+        ],
+        requestBody: new OA\RequestBody(
+            description: 'User registration request data to update',
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/UpdateUserRegistrationRequestRequest')
+        ),
+        responses: [
+            new OA\Response(
+                response: HttpResponse::HTTP_OK,
+                description: 'OK',
+                content: new OA\JsonContent(ref: '#/components/schemas/UserRegistrationRequest')
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_BAD_REQUEST,
+                description: 'Bad Request'
+            ),
+            new OA\Response(
+                response: HttpResponse::HTTP_PRECONDITION_FAILED,
+                description: 'Precondition Failed'
+            ),
+            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 update($id){
         try {
 

app/Swagger/Models/UserRegistrationRequestSchema.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'UserRegistrationRequest',
+    type: 'object',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/Base'),
+        new OA\Schema(
+            type: 'object',
+            properties: [
+                new OA\Property(property: 'email', type: 'string', description: 'Email address'),
+                new OA\Property(property: 'first_name', type: 'string', description: 'First name'),
+                new OA\Property(property: 'last_name', type: 'string', description: 'Last name'),
+                new OA\Property(property: 'country', type: 'string', description: 'Country ISO alpha-2 code'),
+                new OA\Property(property: 'hash', type: 'string', description: 'Registration request hash'),
+                new OA\Property(property: 'set_password_link', type: 'string', format: 'uri', description: 'Link to set password'),
+            ]
+        )
+    ]
+)]
+class UserRegistrationRequestSchema
+{
+}

app/Swagger/OAuth2UserRegistrationRequestApiControllerSchemas.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'PaginatedUserRegistrationRequestResponse',
+    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/UserRegistrationRequest')
+                )
+            ]
+        )
+    ]
+)]
+class PaginatedUserRegistrationRequestResponseSchema
+{
+}

app/Swagger/Requests/CreateUserRegistrationRequestRequestSchema.php

@@ -0,0 +1,45 @@
+<?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: 'CreateUserRegistrationRequestRequest',
+    title: 'Create User Registration Request',
+    description: 'Request body for creating a user registration request',
+    required: ['email'],
+    type: 'object',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/UserRegistrationRequestFields'),
+        new OA\Schema(
+            properties: [
+                new OA\Property(
+                    property: 'email',
+                    type: 'string',
+                    description: 'Email address',
+                    format: 'email',
+                    maxLength: 255
+                ),
+                new OA\Property(
+                    property: 'country',
+                    type: 'string',
+                    description: 'Country ISO alpha-2 code',
+                ),
+            ]
+        ),
+    ]
+)]
+class CreateUserRegistrationRequestRequestSchema
+{
+}

app/Swagger/Requests/UpdateUserRegistrationRequestRequestSchema.php

@@ -0,0 +1,38 @@
+<?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: 'UpdateUserRegistrationRequestRequest',
+    title: 'Update User Registration Request',
+    description: 'Request body for updating a user registration request. All fields are optional.',
+    type: 'object',
+    allOf: [
+        new OA\Schema(ref: '#/components/schemas/UserRegistrationRequestFields'),
+        new OA\Schema(
+            properties: [
+                new OA\Property(
+                    property: 'country',
+                    type: 'string',
+                    description: 'Country ISO alpha-2 code',
+                    nullable: true
+                ),
+            ]
+        ),
+    ]
+)]
+class UpdateUserRegistrationRequestRequestSchema
+{
+}

app/Swagger/Requests/UserRegistrationRequestFieldsSchema.php

@@ -0,0 +1,48 @@
+<?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: 'UserRegistrationRequestFields',
+    title: 'User Registration Request Fields',
+    description: 'Common fields for user registration request operations',
+    type: 'object',
+    properties: [
+        new OA\Property(
+            property: 'first_name',
+            type: 'string',
+            description: 'First name',
+            maxLength: 100,
+            nullable: true
+        ),
+        new OA\Property(
+            property: 'last_name',
+            type: 'string',
+            description: 'Last name',
+            maxLength: 100,
+            nullable: true
+        ),
+        new OA\Property(
+            property: 'company',
+            type: 'string',
+            description: 'Company name',
+            maxLength: 100,
+            nullable: true
+        ),
+    ]
+)]
+class UserRegistrationRequestFieldsSchema
+{
+}

app/Swagger/Security/OAuth2UserRegistrationRequestApiControllerSecurityScheme.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 App\libs\OAuth2\IUserScopes;
+use OpenApi\Attributes as OA;
+
+#[OA\SecurityScheme(
+    securityScheme: "OAuth2UserRegistrationRequestApi",
+    type: "oauth2",
+    flows: [
+        new OA\Flow(
+            flow: 'authorizationCode',
+            authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
+            tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+            scopes: [
+                IUserScopes::Registration => "User registration",
+            ]
+        ),
+    ]
+)]
+class OAuth2UserRegistrationRequestApiControllerSecurityScheme
+{
+}