Skip to content

Commit 7f4b4a9

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

7 files changed

Lines changed: 358 additions & 0 deletions

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

Lines changed: 141 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,65 @@ 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: 'expand',
72+
description: 'Expand relations',
73+
in: 'query',
74+
required: false,
75+
schema: new OA\Schema(type: 'string')
76+
),
77+
new OA\Parameter(
78+
name: 'filter',
79+
description: 'Filter criteria (first_name, last_name, email, is_redeemed)',
80+
in: 'query',
81+
required: false,
82+
schema: new OA\Schema(type: 'string')
83+
),
84+
new OA\Parameter(
85+
name: 'order',
86+
description: 'Order criteria (id)',
87+
in: 'query',
88+
required: false,
89+
schema: new OA\Schema(type: 'string')
90+
),
91+
],
92+
responses: [
93+
new OA\Response(
94+
response: HttpResponse::HTTP_OK,
95+
description: 'OK',
96+
content: new OA\JsonContent(ref: '#/components/schemas/PaginatedUserRegistrationRequestResponse')
97+
),
98+
new OA\Response(
99+
response: HttpResponse::HTTP_PRECONDITION_FAILED,
100+
description: 'Precondition Failed'
101+
),
102+
new OA\Response(
103+
response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
104+
description: 'Server Error'
105+
),
106+
]
107+
)]
46108
public function __construct
47109
(
48110
IUserRegistrationRequestRepository $repository,
@@ -97,6 +159,41 @@ protected function getFilterValidatorRules(): array
97159
/**
98160
* @return \Illuminate\Http\JsonResponse|mixed
99161
*/
162+
#[OA\Post(
163+
path: '/api/v1/user-registration-requests',
164+
operationId: 'createUserRegistrationRequest',
165+
summary: 'Create a user registration request',
166+
security: [['OAuth2UserRegistrationRequestApi' => [IUserScopes::Registration]]],
167+
tags: ['User Registration Requests'],
168+
requestBody: new OA\RequestBody(
169+
description: 'User registration request data',
170+
required: true,
171+
content: new OA\JsonContent(ref: '#/components/schemas/CreateUserRegistrationRequestRequest')
172+
),
173+
responses: [
174+
new OA\Response(
175+
response: HttpResponse::HTTP_CREATED,
176+
description: 'Created',
177+
content: new OA\JsonContent(ref: '#/components/schemas/UserRegistrationRequest')
178+
),
179+
new OA\Response(
180+
response: HttpResponse::HTTP_BAD_REQUEST,
181+
description: 'Bad Request'
182+
),
183+
new OA\Response(
184+
response: HttpResponse::HTTP_PRECONDITION_FAILED,
185+
description: 'Precondition Failed'
186+
),
187+
new OA\Response(
188+
response: HttpResponse::HTTP_NOT_FOUND,
189+
description: 'Not Found'
190+
),
191+
new OA\Response(
192+
response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
193+
description: 'Server Error'
194+
),
195+
]
196+
)]
100197
public function register(){
101198
try {
102199

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

‎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: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
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: "clientCredentials",
24+
tokenUrl: "/oauth2/token",
25+
scopes: [
26+
IUserScopes::Registration => "User registration",
27+
]
28+
),
29+
]
30+
)]
31+
class OAuth2UserRegistrationRequestApiControllerSecurityScheme
32+
{
33+
}

0 commit comments

Comments
 (0)