Skip to content

Commit ffe89e3

Browse files
matiasperrone-exomatiasperrone-exo
committed
feat: Add OpenAPI documentation annotations for OAuth2UserRegistrationRequestApiController
Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>
1 parent a259529 commit ffe89e3

7 files changed

+352
-0
lines changed

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

Lines changed: 134 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,6 +23,8 @@
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
@@ -43,6 +46,58 @@ final class OAuth2UserRegistrationRequestApiController extends OAuth2ProtectedCo
4346
* @param IResourceServerContext $resource_server_context
4447
* @param ILogService $log_service
4548
*/
49+
#[OA\Get(
50+
path: '/api/v1/user-registration-requests',
51+
operationId: 'getUserRegistrationRequests',
52+
summary: 'Get all user registration requests',
53+
security: [['OAuth2UserRegistrationRequestApi' => [IUserScopes::Registration]]],
54+
tags: ['User Registration Requests'],
55+
parameters: [
56+
new OA\Parameter(
57+
name: 'page',
58+
description: 'Page number',
59+
in: 'query',
60+
required: false,
61+
schema: new OA\Schema(type: 'integer')
62+
),
63+
new OA\Parameter(
64+
name: 'per_page',
65+
description: 'Items per page',
66+
in: 'query',
67+
required: false,
68+
schema: new OA\Schema(type: 'integer')
69+
),
70+
new OA\Parameter(
71+
name: 'filter',
72+
description: 'Filter criteria (first_name, last_name, email, is_redeemed) ("=@" starts with, "==" exact match)',
73+
in: 'query',
74+
required: false,
75+
schema: new OA\Schema(type: 'string')
76+
),
77+
new OA\Parameter(
78+
name: 'order',
79+
description: 'Order criteria (id)',
80+
in: 'query',
81+
required: false,
82+
schema: new OA\Schema(type: 'string')
83+
),
84+
],
85+
responses: [
86+
new OA\Response(
87+
response: HttpResponse::HTTP_OK,
88+
description: 'OK',
89+
content: new OA\JsonContent(ref: '#/components/schemas/PaginatedUserRegistrationRequestResponse')
90+
),
91+
new OA\Response(
92+
response: HttpResponse::HTTP_PRECONDITION_FAILED,
93+
description: 'Precondition Failed'
94+
),
95+
new OA\Response(
96+
response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
97+
description: 'Server Error'
98+
),
99+
]
100+
)]
46101
public function __construct
47102
(
48103
IUserRegistrationRequestRepository $repository,
@@ -97,6 +152,41 @@ protected function getFilterValidatorRules(): array
97152
/**
98153
* @return \Illuminate\Http\JsonResponse|mixed
99154
*/
155+
#[OA\Post(
156+
path: '/api/v1/user-registration-requests',
157+
operationId: 'createUserRegistrationRequest',
158+
summary: 'Create a user registration request',
159+
security: [['OAuth2UserRegistrationRequestApi' => [IUserScopes::Registration]]],
160+
tags: ['User Registration Requests'],
161+
requestBody: new OA\RequestBody(
162+
description: 'User registration request data',
163+
required: true,
164+
content: new OA\JsonContent(ref: '#/components/schemas/CreateUserRegistrationRequestRequest')
165+
),
166+
responses: [
167+
new OA\Response(
168+
response: HttpResponse::HTTP_CREATED,
169+
description: 'Created',
170+
content: new OA\JsonContent(ref: '#/components/schemas/UserRegistrationRequest')
171+
),
172+
new OA\Response(
173+
response: HttpResponse::HTTP_BAD_REQUEST,
174+
description: 'Bad Request'
175+
),
176+
new OA\Response(
177+
response: HttpResponse::HTTP_PRECONDITION_FAILED,
178+
description: 'Precondition Failed'
179+
),
180+
new OA\Response(
181+
response: HttpResponse::HTTP_NOT_FOUND,
182+
description: 'Not Found'
183+
),
184+
new OA\Response(
185+
response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
186+
description: 'Server Error'
187+
),
188+
]
189+
)]
100190
public function register(){
101191
try {
102192

@@ -148,6 +238,50 @@ public function register(){
148238
* @param $id
149239
* @return \Illuminate\Http\JsonResponse|mixed
150240
*/
241+
#[OA\Put(
242+
path: '/api/v1/user-registration-requests/{id}',
243+
operationId: 'updateUserRegistrationRequest',
244+
summary: 'Update a user registration request',
245+
security: [['OAuth2UserRegistrationRequestApi' => [IUserScopes::Registration]]],
246+
tags: ['User Registration Requests'],
247+
parameters: [
248+
new OA\Parameter(
249+
name: 'id',
250+
description: 'Registration request ID',
251+
in: 'path',
252+
required: true,
253+
schema: new OA\Schema(type: 'integer')
254+
),
255+
],
256+
requestBody: new OA\RequestBody(
257+
description: 'User registration request data to update',
258+
required: true,
259+
content: new OA\JsonContent(ref: '#/components/schemas/UpdateUserRegistrationRequestRequest')
260+
),
261+
responses: [
262+
new OA\Response(
263+
response: HttpResponse::HTTP_OK,
264+
description: 'OK',
265+
content: new OA\JsonContent(ref: '#/components/schemas/UserRegistrationRequest')
266+
),
267+
new OA\Response(
268+
response: HttpResponse::HTTP_BAD_REQUEST,
269+
description: 'Bad Request'
270+
),
271+
new OA\Response(
272+
response: HttpResponse::HTTP_PRECONDITION_FAILED,
273+
description: 'Precondition Failed'
274+
),
275+
new OA\Response(
276+
response: HttpResponse::HTTP_NOT_FOUND,
277+
description: 'Not Found'
278+
),
279+
new OA\Response(
280+
response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
281+
description: 'Server Error'
282+
),
283+
]
284+
)]
151285
public function update($id){
152286
try {
153287

‎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: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
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+
),
39+
]
40+
),
41+
]
42+
)]
43+
class CreateUserRegistrationRequestRequestSchema
44+
{
45+
}

‎app/Swagger/Requests/UpdateUserRegistrationRequestRequestSchema.php‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
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+
nullable: true
31+
),
32+
]
33+
),
34+
]
35+
)]
36+
class UpdateUserRegistrationRequestRequestSchema
37+
{
38+
}

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

‎app/Swagger/Security/OAuth2UserRegistrationRequestApiControllerSecurityScheme.php‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
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 App\libs\OAuth2\IUserScopes;
16+
use OpenApi\Attributes as OA;
17+
18+
#[OA\SecurityScheme(
19+
securityScheme: "OAuth2UserRegistrationRequestApi",
20+
type: "oauth2",
21+
flows: [
22+
new OA\Flow(
23+
flow: 'authorizationCode',
24+
authorizationUrl: '/oauth2/auth',
25+
tokenUrl: '/oauth2/token',
26+
scopes: [
27+
IUserScopes::Registration => "User registration",
28+
]
29+
),
30+
]
31+
)]
32+
class OAuth2UserRegistrationRequestApiControllerSecurityScheme
33+
{
34+
}

0 commit comments

Comments
 (0)