Skip to content

Commit 53f5b6d

Browse files
andrestejerina97matiasperrone
andrestejerina97
authored and
matiasperrone
committed
feat: Add openapi documentation for OAuth2SponsorshipTypeApiController
1 parent 70dc405 commit 53f5b6d

3 files changed

Lines changed: 321 additions & 15 deletions

File tree

‎app/Http/Controllers/Apis/Protected/Summit/OAuth2SponsorshipTypeApiController.php‎

Lines changed: 196 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,17 @@
1313
**/
1414
use App\Models\Foundation\Summit\Repositories\ISponsorshipTypeRepository;
1515
use App\ModelSerializers\SerializerUtils;
16+
use App\Security\SummitScopes;
1617
use App\Services\Model\ISponsorshipTypeService;
18+
use Illuminate\Support\Facades\Config;
1719
use Illuminate\Support\Facades\Log;
1820
use models\oauth2\IResourceServerContext;
1921
use models\summit\ISummitRepository;
2022
use ModelSerializers\SerializerRegistry;
23+
use App\Models\Foundation\Main\IGroup;
24+
use OpenApi\Attributes as OA;
25+
use Symfony\Component\HttpFoundation\Response;
26+
2127
/**
2228
* Class OAuth2SponsorshipTypeApiController
2329
* @package App\Http\Controllers
@@ -101,9 +107,108 @@ protected function getSummitRepository(): ISummitRepository
101107
}
102108

103109
use GetAndValidateJsonPayload;
104-
/**
105-
* @return \Illuminate\Http\JsonResponse|mixed
106-
*/
110+
111+
#[OA\Get(
112+
path: "/api/v1/sponsorship-types",
113+
summary: "Get all sponsorship types",
114+
operationId: 'getSponsorshipTypes',
115+
x: [
116+
'required-groups' => [
117+
IGroup::SummitAdministrators,
118+
IGroup::SuperAdmins,
119+
IGroup::Administrators
120+
]
121+
],
122+
security: [['summit_sponsorship_oauth2' => [
123+
SummitScopes::ReadSummitData,
124+
SummitScopes::ReadAllSummitData,
125+
]]],
126+
tags: ["SponsorshipTypes"],
127+
parameters: [
128+
new OA\Parameter(name: "page", description: "Page number", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 1)),
129+
new OA\Parameter(name: "per_page", description: "Items per page", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 10)),
130+
new OA\Parameter(name: "filter", description: "Filter query (name==value, label=@value, size==value)", in: "query", required: false, schema: new OA\Schema(type: "string")),
131+
new OA\Parameter(name: "order", description: "Order by (+id, -name, +order, +label, +size)", in: "query", required: false, schema: new OA\Schema(type: "string")),
132+
],
133+
responses: [
134+
new OA\Response(
135+
response: Response::HTTP_OK,
136+
description: "OK",
137+
content: new OA\JsonContent(ref: '#/components/schemas/PaginatedDataSponsorshipType'),
138+
),
139+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
140+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
141+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
142+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
143+
]
144+
)]
145+
public function getAll()
146+
{
147+
return $this->_getAll(
148+
function(){
149+
return [
150+
'name' => ['==', '=@'],
151+
'label' => ['==', '=@'],
152+
'size' => ['==', '=@'],
153+
];
154+
},
155+
function(){
156+
return [
157+
'name' => 'sometimes|required|string',
158+
'label' => 'sometimes|required|string',
159+
'size' => 'sometimes|required|string',
160+
];
161+
},
162+
function(){
163+
return [
164+
'id',
165+
'name',
166+
'order',
167+
'label',
168+
'size',
169+
];
170+
},
171+
function($filter){
172+
return $filter;
173+
},
174+
function(){
175+
return SerializerRegistry::SerializerType_Public;
176+
}
177+
);
178+
}
179+
180+
#[OA\Post(
181+
path: "/api/v1/sponsorship-types",
182+
summary: "Add a new sponsorship type",
183+
operationId: 'addSponsorshipType',
184+
x: [
185+
'required-groups' => [
186+
IGroup::SummitAdministrators,
187+
IGroup::SuperAdmins,
188+
IGroup::Administrators
189+
]
190+
],
191+
security: [['summit_sponsorship_oauth2' => [
192+
SummitScopes::WriteSummitData,
193+
]]],
194+
tags: ["SponsorshipTypes"],
195+
requestBody: new OA\RequestBody(
196+
required: true,
197+
content: new OA\JsonContent(ref: "#/components/schemas/SponsorshipTypeAddRequest")
198+
),
199+
responses: [
200+
new OA\Response(
201+
response: Response::HTTP_CREATED,
202+
description: "Created",
203+
content: new OA\JsonContent(ref: "#/components/schemas/SponsorshipType")
204+
),
205+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
206+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
207+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
208+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
209+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
210+
]
211+
)]
107212
public function add()
108213
{
109214
return $this->processRequest(function(){
@@ -124,10 +229,31 @@ public function add()
124229
});
125230
}
126231

127-
/**
128-
* @param $id
129-
* @return \Illuminate\Http\JsonResponse|mixed
130-
*/
232+
#[OA\Get(
233+
path: "/api/v1/sponsorship-types/{id}",
234+
summary: "Get a sponsorship type by id",
235+
operationId: 'getSponsorshipType',
236+
security: [['summit_sponsorship_oauth2' => [
237+
SummitScopes::ReadSummitData,
238+
SummitScopes::ReadAllSummitData,
239+
]]],
240+
tags: ["SponsorshipTypes"],
241+
parameters: [
242+
new OA\Parameter(name: "id", description: "Sponsorship Type ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
243+
],
244+
responses: [
245+
new OA\Response(
246+
response: Response::HTTP_OK,
247+
description: "OK",
248+
content: new OA\JsonContent(ref: "#/components/schemas/SponsorshipType")
249+
),
250+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
251+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
252+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
253+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
254+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
255+
]
256+
)]
131257
public function get($id)
132258
{
133259
return $this->processRequest(function() use($id){
@@ -144,10 +270,42 @@ public function get($id)
144270
});
145271
}
146272

147-
/**
148-
* @param $id
149-
* @return \Illuminate\Http\JsonResponse|mixed
150-
*/
273+
#[OA\Put(
274+
path: "/api/v1/sponsorship-types/{id}",
275+
summary: "Update a sponsorship type",
276+
operationId: 'updateSponsorshipType',
277+
x: [
278+
'required-groups' => [
279+
IGroup::SummitAdministrators,
280+
IGroup::SuperAdmins,
281+
IGroup::Administrators
282+
]
283+
],
284+
security: [['summit_sponsorship_oauth2' => [
285+
SummitScopes::WriteSummitData,
286+
]]],
287+
tags: ["SponsorshipTypes"],
288+
parameters: [
289+
new OA\Parameter(name: "id", description: "Sponsorship Type ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
290+
],
291+
requestBody: new OA\RequestBody(
292+
required: true,
293+
content: new OA\JsonContent(ref: "#/components/schemas/SponsorshipTypeUpdateRequest")
294+
),
295+
responses: [
296+
new OA\Response(
297+
response: Response::HTTP_OK,
298+
description: "OK",
299+
content: new OA\JsonContent(ref: "#/components/schemas/SponsorshipType")
300+
),
301+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
302+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
303+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
304+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
305+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
306+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
307+
]
308+
)]
151309
public function update($id)
152310
{
153311
return $this->processRequest(function() use($id){
@@ -168,10 +326,33 @@ public function update($id)
168326
});
169327
}
170328

171-
/**
172-
* @param $id
173-
* @return \Illuminate\Http\JsonResponse|mixed
174-
*/
329+
#[OA\Delete(
330+
path: "/api/v1/sponsorship-types/{id}",
331+
summary: "Delete a sponsorship type",
332+
operationId: 'deleteSponsorshipType',
333+
x: [
334+
'required-groups' => [
335+
IGroup::SummitAdministrators,
336+
IGroup::SuperAdmins,
337+
IGroup::Administrators
338+
]
339+
],
340+
security: [['summit_sponsorship_oauth2' => [
341+
SummitScopes::WriteSummitData,
342+
]]],
343+
tags: ["SponsorshipTypes"],
344+
parameters: [
345+
new OA\Parameter(name: "id", description: "Sponsorship Type ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
346+
],
347+
responses: [
348+
new OA\Response(response: Response::HTTP_NO_CONTENT, description: "No Content"),
349+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
350+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
351+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
352+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
353+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
354+
]
355+
)]
175356
public function delete($id)
176357
{
177358
return $this->processRequest(function() use($id){

‎app/Swagger/Security/SponsorshipTypeOauthSchemas.php‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<?php
2+
namespace App\Swagger\schemas;
3+
4+
use App\Security\SummitScopes;
5+
use OpenApi\Attributes as OA;
6+
7+
#[
8+
OA\SecurityScheme(
9+
type: 'oauth2',
10+
securityScheme: 'summit_sponsorship_oauth2',
11+
flows: [
12+
new OA\Flow(
13+
authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
14+
tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
15+
flow: 'authorizationCode',
16+
scopes: [
17+
SummitScopes::ReadSummitData => 'Read Sponsorship Types Data',
18+
SummitScopes::WriteSummitData => 'Write Sponsorship Types Data',
19+
],
20+
),
21+
],
22+
)
23+
]
24+
class SponsorshipTypeAuthSchema {}

‎app/Swagger/SponsorshipTypeSchemas.php‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use App\Security\SummitScopes;
6+
use OpenApi\Attributes as OA;
7+
use Symfony\Component\HttpFoundation\Response;
8+
9+
#[OA\Schema(
10+
schema: 'PaginatedDataSponsorshipType',
11+
description: 'Paginated response containing sponsorship types',
12+
allOf: [
13+
new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
14+
new OA\Schema(
15+
type: 'object',
16+
properties: [
17+
new OA\Property(
18+
property: 'data',
19+
type: 'array',
20+
items: new OA\Items(ref: '#/components/schemas/SponsorshipType'),
21+
description: 'Array of sponsorship type objects'
22+
)
23+
]
24+
)
25+
]
26+
)]
27+
class PaginatedDataSponsorshipTypeSchemas {}
28+
29+
#[OA\Schema(
30+
schema: 'SponsorshipType',
31+
type: 'object',
32+
properties: [
33+
new OA\Property(
34+
property: 'id',
35+
type: 'integer',
36+
description: 'Sponsorship type identifier'
37+
),
38+
new OA\Property(
39+
property: 'created',
40+
type: 'integer',
41+
format: 'int64',
42+
description: 'Creation timestamp (UNIX epoch)'
43+
),
44+
new OA\Property(
45+
property: 'last_edited',
46+
type: 'integer',
47+
format: 'int64',
48+
description: 'Last modification timestamp (UNIX epoch)'
49+
),
50+
new OA\Property(
51+
property: 'name',
52+
type: 'string',
53+
description: 'Sponsorship type name'
54+
),
55+
new OA\Property(
56+
property: 'label',
57+
type: 'string',
58+
description: 'Sponsorship type display label'
59+
),
60+
new OA\Property(
61+
property: 'order',
62+
type: 'integer',
63+
description: 'Display order'
64+
),
65+
new OA\Property(
66+
property: 'size',
67+
type: 'string',
68+
description: 'Sponsorship size category (Small, Medium, Large, Big)'
69+
),
70+
]
71+
)]
72+
class SponsorshipTypeSchemas {}
73+
74+
75+
76+
#[OA\Schema(
77+
schema: 'SponsorshipTypeAddRequest',
78+
type: 'object',
79+
required: ['name', 'label', 'size'],
80+
description: 'Request to create a new sponsorship type',
81+
properties: [
82+
new OA\Property(property: 'name', type: 'string'),
83+
new OA\Property(property: 'label', type: 'string'),
84+
new OA\Property(property: 'size', type: 'string', enum: ['Small', 'Medium', 'Large', 'Big']),
85+
]
86+
)]
87+
class SponsorshipTypeAddRequest {}
88+
89+
90+
#[OA\Schema(
91+
schema: 'SponsorshipTypeUpdateRequest',
92+
type: 'object',
93+
description: 'Request to update an existing sponsorship type (all fields optional)',
94+
properties: [
95+
new OA\Property(property: 'name', type: 'string'),
96+
new OA\Property(property: 'label', type: 'string'),
97+
new OA\Property(property: 'size', type: 'string', enum: ['Small', 'Medium', 'Large', 'Big']),
98+
new OA\Property(property: 'order', type: 'integer', minimum: 1),
99+
]
100+
)]
101+
class SponsorshipTypeUpdateRequest {}

0 commit comments

Comments
 (0)