Skip to content

Commit 49a3bef

Browse files
andrestejerina97andrestejerina97
committed
feat: Add openapi documentation for OAuth2SummitSubmittersApiController
1 parent abbde7c commit 49a3bef

3 files changed

Lines changed: 297 additions & 12 deletions

File tree

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

Lines changed: 177 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@
1313
**/
1414

1515
use App\ModelSerializers\IMemberSerializerTypes;
16+
use App\Models\Foundation\Main\IGroup;
17+
use App\Security\SummitScopes;
1618
use Illuminate\Support\Facades\Request;
1719
use models\main\IMemberRepository;
1820
use models\oauth2\IResourceServerContext;
@@ -21,6 +23,8 @@
2123
use utils\Filter;
2224
use utils\FilterParser;
2325
use utils\PagingInfo;
26+
use OpenApi\Attributes as OA;
27+
use Symfony\Component\HttpFoundation\Response;
2428

2529
/**
2630
* Class OAuth2SummitSubmittersApiController
@@ -66,10 +70,72 @@ public function __construct
6670
$this->service = $service;
6771
}
6872

69-
/**
70-
* @param $summit_id
71-
* @return \Illuminate\Http\JsonResponse|mixed
72-
*/
73+
#[OA\Get(
74+
path: "/api/v1/summits/{id}/submitters",
75+
summary: "Get all submitters for a summit",
76+
operationId: "getSubmittersBySummit",
77+
tags: ["SummitSubmitters"],
78+
security: [['summit_submitters_oauth2' => [
79+
SummitScopes::ReadSummitData,
80+
SummitScopes::ReadAllSummitData,
81+
]]],
82+
parameters: [
83+
new OA\Parameter(
84+
name: "id",
85+
in: "path",
86+
required: true,
87+
description: "Summit ID or slug",
88+
schema: new OA\Schema(type: "string")
89+
),
90+
new OA\Parameter(
91+
name: "page",
92+
in: "query",
93+
required: false,
94+
description: "Page number",
95+
schema: new OA\Schema(type: "integer", default: 1)
96+
),
97+
new OA\Parameter(
98+
name: "per_page",
99+
in: "query",
100+
required: false,
101+
description: "Items per page",
102+
schema: new OA\Schema(type: "integer", default: 10)
103+
),
104+
new OA\Parameter(
105+
name: "filter",
106+
in: "query",
107+
required: false,
108+
description: "Filter query (supports multiple operators)",
109+
schema: new OA\Schema(type: "string", example: "first_name=@John")
110+
),
111+
new OA\Parameter(
112+
name: "order",
113+
in: "query",
114+
required: false,
115+
description: "Order by field (prefix with - for descending)",
116+
schema: new OA\Schema(type: "string", example: "first_name,-created")
117+
),
118+
new OA\Parameter(
119+
name: "expand",
120+
in: "query",
121+
required: false,
122+
description: "Expand relations (presentations, member)",
123+
schema: new OA\Schema(type: "string", example: "presentations,member")
124+
),
125+
],
126+
responses: [
127+
new OA\Response(
128+
response: Response::HTTP_OK,
129+
description: "Successful response with paginated submitters",
130+
content: new OA\JsonContent(ref: '#/components/schemas/PaginatedSubmittersResponse')
131+
),
132+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
133+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
134+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
135+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Summit not found"),
136+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
137+
]
138+
)]
73139
public function getAllBySummit($summit_id)
74140
{
75141
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find(intval($summit_id));
@@ -158,10 +224,62 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use ($summit) {
158224
);
159225
}
160226

161-
/**
162-
* @param $summit_id
163-
* @return \Illuminate\Http\JsonResponse|mixed
164-
*/
227+
#[OA\Get(
228+
path: "/api/v1/summits/{id}/submitters/csv",
229+
description: "required-groups " . IGroup::SummitAdministrators . ", " . IGroup::SuperAdmins . ", " . IGroup::Administrators,
230+
summary: "Get all submitters for a summit in CSV format",
231+
operationId: "getSubmittersCSV",
232+
tags: ["SummitSubmitters"],
233+
security: [['summit_submitters_oauth2' => [
234+
SummitScopes::ReadSummitData,
235+
SummitScopes::ReadAllSummitData,
236+
]]],
237+
x: [
238+
'required-groups' => [
239+
IGroup::SummitAdministrators,
240+
IGroup::SuperAdmins,
241+
IGroup::Administrators,
242+
]
243+
],
244+
parameters: [
245+
new OA\Parameter(
246+
name: "id",
247+
in: "path",
248+
required: true,
249+
description: "Summit ID or slug",
250+
schema: new OA\Schema(type: "string")
251+
),
252+
new OA\Parameter(
253+
name: "filter",
254+
in: "query",
255+
required: false,
256+
description: "Filter query to select specific submitters",
257+
schema: new OA\Schema(type: "string", example: "first_name=@John")
258+
),
259+
new OA\Parameter(
260+
name: "order",
261+
in: "query",
262+
required: false,
263+
description: "Order by field (prefix with - for descending)",
264+
schema: new OA\Schema(type: "string", example: "first_name,-created")
265+
),
266+
],
267+
responses: [
268+
new OA\Response(
269+
response: Response::HTTP_OK,
270+
description: "CSV file with submitter data",
271+
content: new OA\MediaType(
272+
mediaType: "text/csv",
273+
schema: new OA\Schema(type: "string", format: "binary")
274+
)
275+
),
276+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
277+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
278+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
279+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Summit not found"),
280+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
281+
]
282+
)]
165283
public function getAllBySummitCSV($summit_id)
166284
{
167285
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find(intval($summit_id));
@@ -255,10 +373,57 @@ function ($page, $per_page, $filter, $order, $applyExtraFilters) use ($summit) {
255373
);
256374
}
257375

258-
/**
259-
* @param $summit_id
260-
* @return \Illuminate\Http\JsonResponse|mixed
261-
*/
376+
#[OA\Put(
377+
path: "/api/v1/summits/{id}/submitters/all/send",
378+
description: "required-groups " . IGroup::SummitAdministrators . ", " . IGroup::SuperAdmins . ", " . IGroup::Administrators . ", " . IGroup::SummitRegistrationAdmins,
379+
summary: "Send bulk emails to submitters",
380+
operationId: "sendSubmittersBulkEmails",
381+
tags: ["SummitSubmitters"],
382+
security: [['summit_submitters_oauth2' => [
383+
SummitScopes::WriteSummitData,
384+
SummitScopes::WriteSpeakersData,
385+
]]],
386+
x: [
387+
'required-groups' => [
388+
IGroup::SummitAdministrators,
389+
IGroup::SuperAdmins,
390+
IGroup::Administrators,
391+
IGroup::SummitRegistrationAdmins,
392+
]
393+
],
394+
parameters: [
395+
new OA\Parameter(
396+
name: "id",
397+
in: "path",
398+
required: true,
399+
description: "Summit ID or slug",
400+
schema: new OA\Schema(type: "string")
401+
),
402+
new OA\Parameter(
403+
name: "filter",
404+
in: "query",
405+
required: false,
406+
description: "Filter query to select specific submitters",
407+
schema: new OA\Schema(type: "string", example: "has_accepted_presentations==true")
408+
),
409+
],
410+
requestBody: new OA\RequestBody(
411+
required: true,
412+
content: new OA\JsonContent(ref: "#/components/schemas/SendSubmittersEmailsRequest")
413+
),
414+
responses: [
415+
new OA\Response(
416+
response: Response::HTTP_OK,
417+
description: "Emails sent successfully"
418+
),
419+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
420+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
421+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
422+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Summit not found"),
423+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
424+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
425+
]
426+
)]
262427
public function send($summit_id)
263428
{
264429
return $this->processRequest(function () use ($summit_id) {

‎app/Swagger/SubmitterSchemas.php‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'Submitter',
9+
type: 'object',
10+
description: 'Submitter extends Member with presentation data',
11+
allOf: [
12+
new OA\Schema(ref: '#/components/schemas/Member'),
13+
new OA\Schema(
14+
type: 'object',
15+
properties: [
16+
new OA\Property(
17+
property: 'accepted_presentations',
18+
type: 'array',
19+
items: new OA\Items(type: 'integer'),
20+
description: 'Array of accepted presentation IDs. Use expand=accepted_presentations to get full objects'
21+
),
22+
new OA\Property(
23+
property: 'alternate_presentations',
24+
type: 'array',
25+
items: new OA\Items(type: 'integer'),
26+
description: 'Array of alternate presentation IDs. Use expand=alternate_presentations to get full objects'
27+
),
28+
new OA\Property(
29+
property: 'rejected_presentations',
30+
type: 'array',
31+
items: new OA\Items(type: 'integer'),
32+
description: 'Array of rejected presentation IDs. Use expand=rejected_presentations to get full objects'
33+
),
34+
]
35+
)
36+
]
37+
)]
38+
class SubmitterSchemas {}
39+
40+
/**
41+
* Paginated Submitters Response
42+
*/
43+
#[OA\Schema(
44+
schema: 'PaginatedSubmittersResponse',
45+
allOf: [
46+
new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'),
47+
new OA\Schema(
48+
type: 'object',
49+
properties: [
50+
new OA\Property(
51+
property: 'data',
52+
type: 'array',
53+
description: 'List of submitters',
54+
items: new OA\Items(ref: '#/components/schemas/Submitter')
55+
)
56+
]
57+
)
58+
]
59+
)]
60+
class PaginatedSubmittersResponseSchema {}
61+
62+
/**
63+
* Send Emails to Submitters Request
64+
*/
65+
#[OA\Schema(
66+
schema: 'SendSubmittersEmailsRequest',
67+
type: 'object',
68+
required: ['subject', 'body'],
69+
properties: [
70+
new OA\Property(
71+
property: 'subject',
72+
type: 'string',
73+
example: 'Important Update for Submitters',
74+
description: 'Email subject'
75+
),
76+
new OA\Property(
77+
property: 'body',
78+
type: 'string',
79+
example: 'Dear Submitter, here is an important update...',
80+
description: 'Email body content'
81+
),
82+
new OA\Property(
83+
property: 'filter',
84+
type: 'string',
85+
example: 'has_accepted_presentations==true',
86+
description: 'Optional filter to select specific submitters'
87+
),
88+
]
89+
)]
90+
class SendSubmittersEmailsRequestSchema {}

‎app/Swagger/security/SummitSubmittersOAuthSchema.php‎

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

0 commit comments

Comments
 (0)