Skip to content

Commit ac9957d

Browse files
matiasperrone-exomatiasperrone-exo
committed
feat: Add OpenAPI documentation annotations for OAuth2UserRegistrationRequestApiController v1 routes
1 parent 0d6b7e3 commit ac9957d

7 files changed

+357
-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,11 +23,65 @@
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_PRECONDITION_FAILED,
77+
description: 'Precondition Failed'
78+
),
79+
new OA\Response(
80+
response: HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
81+
description: 'Server Error'
82+
),
83+
]
84+
)]
3085
final class OAuth2UserRegistrationRequestApiController extends OAuth2ProtectedController
3186
{
3287

@@ -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: 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+
}

‎app/Swagger/Security/OAuth2UserRegistrationRequestApiControllerSecurityScheme.php‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<?php
2+
namespace App\Swagger\schemas;
3+
/**
4+
* Copyright 2025 OpenStack Foundation
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
* Unless required by applicable law or agreed to in writing, software
10+
* distributed under the License is distributed on an "AS IS" BASIS,
11+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
* See the License for the specific language governing permissions and
13+
* limitations under the License.
14+
**/
15+
16+
use App\libs\OAuth2\IUserScopes;
17+
use OpenApi\Attributes as OA;
18+
19+
#[OA\SecurityScheme(
20+
securityScheme: "OAuth2UserRegistrationRequestApi",
21+
type: "oauth2",
22+
flows: [
23+
new OA\Flow(
24+
flow: 'authorizationCode',
25+
authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
26+
tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
27+
scopes: [
28+
IUserScopes::Registration => "User registration",
29+
]
30+
),
31+
]
32+
)]
33+
class OAuth2UserRegistrationRequestApiControllerSecurityScheme
34+
{
35+
}

0 commit comments

Comments
 (0)