Skip to content

Commit 5ad8c11

Browse files
matiasperrone-exomatiasperrone-exo
authored
Feat | Add OpenAPI documentation for OAuth2UserRegistrationRequestApiController (#108)
* feat: Add OpenAPI documentation annotations for OAuth2UserRegistrationRequestApiController v1 routes * chore: Add OpenAPI response annotations for forbidden and unauthorized statuses in OAuth2UserRegistrationRequestApiController
1 parent b19881c commit 5ad8c11

7 files changed

Lines changed: 381 additions & 0 deletions

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

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414

1515
use App\Http\Controllers\GetAllTrait;
1616
use App\libs\Auth\Repositories\IUserRegistrationRequestRepository;
17+
use App\libs\OAuth2\IUserScopes;
1718
use App\ModelSerializers\SerializerRegistry;
1819
use App\Services\Auth\IUserService;
1920
use Illuminate\Support\Facades\Log;
@@ -22,11 +23,73 @@
2223
use models\exceptions\EntityNotFoundException;
2324
use models\exceptions\ValidationException;
2425
use OAuth2\IResourceServerContext;
26+
use OpenApi\Attributes as OA;
27+
use Symfony\Component\HttpFoundation\Response as HttpResponse;
2528
use Utils\Services\ILogService;
2629
/**
2730
* Class OAuth2UserRegistrationRequestApiController
2831
* @package App\Http\Controllers\Api\OAuth2
2932
*/
33+
#[OA\Get(
34+
path: '/api/v1/user-registration-requests',
35+
operationId: 'getUserRegistrationRequests',
36+
summary: 'Get all user registration requests',
37+
security: [['OAuth2UserRegistrationRequestApi' => [IUserScopes::Registration]]],
38+
tags: ['User Registration Requests'],
39+
parameters: [
40+
new OA\Parameter(
41+
name: 'page',
42+
description: 'Page number',
43+
in: 'query',
44+
required: false,
45+
schema: new OA\Schema(type: 'integer')
46+
),
47+
new OA\Parameter(
48+
name: 'per_page',
49+
description: 'Items per page',
50+
in: 'query',
51+
required: false,
52+
schema: new OA\Schema(type: 'integer')
53+
),
54+
new OA\Parameter(
55+
name: 'filter',
56+
description: 'Filter criteria (first_name, last_name, email, is_redeemed) ("=@" starts with, "==" exact match); is_redeemed supports "==" only.',
57+
in: 'query',
58+
required: false,
59+
schema: new OA\Schema(type: 'string')
60+
),
61+
new OA\Parameter(
62+
name: 'order',
63+
description: 'Order criteria. Accepted fields: id. Use +id for ascending, -id for descending.',
64+
in: 'query',
65+
required: false,
66+
schema: new OA\Schema(type: 'string')
67+
),
68+
],
69+
responses: [
70+
new OA\Response(
71+
response: HttpResponse::HTTP_OK,
72+
description: 'OK',
73+
content: new OA\JsonContent(ref: '#/components/schemas/PaginatedUserRegistrationRequestResponse')
74+
),
75+
new OA\Response(
76+
response: HttpResponse::HTTP_FORBIDDEN,
77+
description: 'Forbidden'
78+
),
79+
new OA\Response(
80+
response: HttpResponse::HTTP_UNAUTHORIZED,
81+
description: 'Unauthorized'
82+
),
83+
new OA\Response(
84+
response: HttpResponse::HTTP_PRECONDITION_FAILED,
85+
description: 'Precondition Failed'
86+
),
87+
new OA\Response(
88+
response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
89+
description: 'Server Error'
90+
),
91+
]
92+
)]
3093
final class OAuth2UserRegistrationRequestApiController extends OAuth2ProtectedController
3194
{
3295

@@ -97,6 +160,49 @@ protected function getFilterValidatorRules(): array
97160
/**
98161
* @return \Illuminate\Http\JsonResponse|mixed
99162
*/
163+
#[OA\Post(
164+
path: '/api/v1/user-registration-requests',
165+
operationId: 'createUserRegistrationRequest',
166+
summary: 'Create a user registration request',
167+
security: [['OAuth2UserRegistrationRequestApi' => [IUserScopes::Registration]]],
168+
tags: ['User Registration Requests'],
169+
requestBody: new OA\RequestBody(
170+
description: 'User registration request data',
171+
required: true,
172+
content: new OA\JsonContent(ref: '#/components/schemas/CreateUserRegistrationRequestRequest')
173+
),
174+
responses: [
175+
new OA\Response(
176+
response: HttpResponse::HTTP_CREATED,
177+
description: 'Created',
178+
content: new OA\JsonContent(ref: '#/components/schemas/UserRegistrationRequest')
179+
),
180+
new OA\Response(
181+
response: HttpResponse::HTTP_FORBIDDEN,
182+
description: 'Forbidden'
183+
),
184+
new OA\Response(
185+
response: HttpResponse::HTTP_UNAUTHORIZED,
186+
description: 'Unauthorized'
187+
),
188+
new OA\Response(
189+
response: HttpResponse::HTTP_BAD_REQUEST,
190+
description: 'Bad Request'
191+
),
192+
new OA\Response(
193+
response: HttpResponse::HTTP_PRECONDITION_FAILED,
194+
description: 'Precondition Failed'
195+
),
196+
new OA\Response(
197+
response: HttpResponse::HTTP_NOT_FOUND,
198+
description: 'Not Found'
199+
),
200+
new OA\Response(
201+
response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
202+
description: 'Server Error'
203+
),
204+
]
205+
)]
100206
public function register(){
101207
try {
102208

@@ -148,6 +254,58 @@ public function register(){
148254
* @param $id
149255
* @return \Illuminate\Http\JsonResponse|mixed
150256
*/
257+
#[OA\Put(
258+
path: '/api/v1/user-registration-requests/{id}',
259+
operationId: 'updateUserRegistrationRequest',
260+
summary: 'Update a user registration request',
261+
security: [['OAuth2UserRegistrationRequestApi' => [IUserScopes::Registration]]],
262+
tags: ['User Registration Requests'],
263+
parameters: [
264+
new OA\Parameter(
265+
name: 'id',
266+
description: 'Registration request ID',
267+
in: 'path',
268+
required: true,
269+
schema: new OA\Schema(type: 'integer')
270+
),
271+
],
272+
requestBody: new OA\RequestBody(
273+
description: 'User registration request data to update',
274+
required: true,
275+
content: new OA\JsonContent(ref: '#/components/schemas/UpdateUserRegistrationRequestRequest')
276+
),
277+
responses: [
278+
new OA\Response(
279+
response: HttpResponse::HTTP_CREATED,
280+
description: 'Updated',
281+
content: new OA\JsonContent(ref: '#/components/schemas/UserRegistrationRequest')
282+
),
283+
new OA\Response(
284+
response: HttpResponse::HTTP_FORBIDDEN,
285+
description: 'Forbidden'
286+
),
287+
new OA\Response(
288+
response: HttpResponse::HTTP_UNAUTHORIZED,
289+
description: 'Unauthorized'
290+
),
291+
new OA\Response(
292+
response: HttpResponse::HTTP_BAD_REQUEST,
293+
description: 'Bad Request'
294+
),
295+
new OA\Response(
296+
response: HttpResponse::HTTP_PRECONDITION_FAILED,
297+
description: 'Precondition Failed'
298+
),
299+
new OA\Response(
300+
response: HttpResponse::HTTP_NOT_FOUND,
301+
description: 'Not Found'
302+
),
303+
new OA\Response(
304+
response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
305+
description: 'Server Error'
306+
),
307+
]
308+
)]
151309
public function update($id){
152310
try {
153311

‎app/Swagger/Models/UserRegistrationRequestSchema.php‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'UserRegistrationRequest',
9+
type: 'object',
10+
allOf: [
11+
new OA\Schema(ref: '#/components/schemas/Base'),
12+
new OA\Schema(
13+
type: 'object',
14+
properties: [
15+
new OA\Property(property: 'email', type: 'string', description: 'Email address'),
16+
new OA\Property(property: 'first_name', type: 'string', description: 'First name'),
17+
new OA\Property(property: 'last_name', type: 'string', description: 'Last name'),
18+
new OA\Property(property: 'country', type: 'string', description: 'Country ISO alpha-2 code'),
19+
new OA\Property(property: 'hash', type: 'string', description: 'Registration request hash'),
20+
new OA\Property(property: 'set_password_link', type: 'string', format: 'uri', description: 'Link to set password'),
21+
]
22+
)
23+
]
24+
)]
25+
class UserRegistrationRequestSchema
26+
{
27+
}

‎app/Swagger/OAuth2UserRegistrationRequestApiControllerSchemas.php‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'PaginatedUserRegistrationRequestResponse',
9+
type: 'object',
10+
allOf: [
11+
new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
12+
new OA\Schema(
13+
type: 'object',
14+
properties: [
15+
new OA\Property(
16+
property: 'data',
17+
type: 'array',
18+
items: new OA\Items(ref: '#/components/schemas/UserRegistrationRequest')
19+
)
20+
]
21+
)
22+
]
23+
)]
24+
class PaginatedUserRegistrationRequestResponseSchema
25+
{
26+
}

‎app/Swagger/Requests/CreateUserRegistrationRequestRequestSchema.php‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
<?php namespace App\Swagger\schemas;
2+
/**
3+
* Copyright 2025 OpenStack Foundation
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
* http://www.apache.org/licenses/LICENSE-2.0
8+
* Unless required by applicable law or agreed to in writing, software
9+
* distributed under the License is distributed on an "AS IS" BASIS,
10+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
* See the License for the specific language governing permissions and
12+
* limitations under the License.
13+
**/
14+
15+
use OpenApi\Attributes as OA;
16+
17+
#[OA\Schema(
18+
schema: 'CreateUserRegistrationRequestRequest',
19+
title: 'Create User Registration Request',
20+
description: 'Request body for creating a user registration request',
21+
required: ['email'],
22+
type: 'object',
23+
allOf: [
24+
new OA\Schema(ref: '#/components/schemas/UserRegistrationRequestFields'),
25+
new OA\Schema(
26+
properties: [
27+
new OA\Property(
28+
property: 'email',
29+
type: 'string',
30+
description: 'Email address',
31+
format: 'email',
32+
maxLength: 255
33+
),
34+
new OA\Property(
35+
property: 'country',
36+
type: 'string',
37+
description: 'Country ISO alpha-2 code',
38+
minLength: 2,
39+
maxLength: 2
40+
),
41+
]
42+
),
43+
]
44+
)]
45+
class CreateUserRegistrationRequestRequestSchema
46+
{
47+
}

‎app/Swagger/Requests/UpdateUserRegistrationRequestRequestSchema.php‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<?php namespace App\Swagger\schemas;
2+
/**
3+
* Copyright 2025 OpenStack Foundation
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
* http://www.apache.org/licenses/LICENSE-2.0
8+
* Unless required by applicable law or agreed to in writing, software
9+
* distributed under the License is distributed on an "AS IS" BASIS,
10+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
* See the License for the specific language governing permissions and
12+
* limitations under the License.
13+
**/
14+
15+
use OpenApi\Attributes as OA;
16+
17+
#[OA\Schema(
18+
schema: 'UpdateUserRegistrationRequestRequest',
19+
title: 'Update User Registration Request',
20+
description: 'Request body for updating a user registration request. All fields are optional.',
21+
type: 'object',
22+
allOf: [
23+
new OA\Schema(ref: '#/components/schemas/UserRegistrationRequestFields'),
24+
new OA\Schema(
25+
properties: [
26+
new OA\Property(
27+
property: 'country',
28+
type: 'string',
29+
description: 'Country ISO alpha-2 code',
30+
minLength: 2,
31+
maxLength: 2,
32+
nullable: true
33+
),
34+
]
35+
),
36+
]
37+
)]
38+
class UpdateUserRegistrationRequestRequestSchema
39+
{
40+
}

‎app/Swagger/Requests/UserRegistrationRequestFieldsSchema.php‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
<?php namespace App\Swagger\schemas;
2+
/**
3+
* Copyright 2025 OpenStack Foundation
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
* http://www.apache.org/licenses/LICENSE-2.0
8+
* Unless required by applicable law or agreed to in writing, software
9+
* distributed under the License is distributed on an "AS IS" BASIS,
10+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
* See the License for the specific language governing permissions and
12+
* limitations under the License.
13+
**/
14+
15+
use OpenApi\Attributes as OA;
16+
17+
#[OA\Schema(
18+
schema: 'UserRegistrationRequestFields',
19+
title: 'User Registration Request Fields',
20+
description: 'Common fields for user registration request operations',
21+
type: 'object',
22+
properties: [
23+
new OA\Property(
24+
property: 'first_name',
25+
type: 'string',
26+
description: 'First name',
27+
maxLength: 100,
28+
nullable: true
29+
),
30+
new OA\Property(
31+
property: 'last_name',
32+
type: 'string',
33+
description: 'Last name',
34+
maxLength: 100,
35+
nullable: true
36+
),
37+
new OA\Property(
38+
property: 'company',
39+
type: 'string',
40+
description: 'Company name',
41+
maxLength: 100,
42+
nullable: true
43+
),
44+
]
45+
)]
46+
class UserRegistrationRequestFieldsSchema
47+
{
48+
}

0 commit comments

Comments
 (0)