Skip to content

Commit b99c944

Browse files
andrestejerina97andrestejerina97
committed
feat: Add openapi documentation for OAuth2SummitTrackChairsApiController
1 parent 12cea6a commit b99c944

File tree

3 files changed

+469
-20
lines changed

3 files changed

+469
-20
lines changed

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

Lines changed: 329 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
use App\Http\Utils\EpochCellFormatter;
1717
use App\Models\Foundation\Main\IGroup;
1818
use App\Models\Foundation\Summit\Repositories\ISummitTrackChairRepository;
19+
use App\Security\SummitScopes;
1920
use App\Services\Model\ITrackChairService;
2021
use Illuminate\Support\Facades\Log;
2122
use Illuminate\Support\Facades\Request;
@@ -26,9 +27,12 @@
2627
use models\summit\Summit;
2728
use models\utils\IEntity;
2829
use ModelSerializers\SerializerRegistry;
30+
use OpenApi\Attributes as OA;
31+
use Symfony\Component\HttpFoundation\Response;
2932
use utils\Filter;
3033
use utils\FilterElement;
3134
use Exception;
35+
3236
/**
3337
* Class OAuth2SummitTrackChairsApiController
3438
* @package App\Http\Controllers
@@ -69,10 +73,46 @@ public function __construct
6973

7074
use ParametrizedGetAll;
7175

72-
/**
73-
* @param $summit_id
74-
* @return \Illuminate\Http\JsonResponse|mixed
75-
*/
76+
#[OA\Get(
77+
path: "/api/v1/summits/{id}/track-chairs",
78+
summary: "Get all track chairs for a summit",
79+
description: "Returns different data based on user role: Public view for regular users, Admin view for admins/track chairs",
80+
security: [['summit_track_chairs_oauth2' => [
81+
SummitScopes::ReadSummitData,
82+
SummitScopes::ReadAllSummitData,
83+
]]],
84+
tags: ["TrackChairs"],
85+
x: [
86+
'required-groups' => [
87+
IGroup::SuperAdmins,
88+
IGroup::Administrators,
89+
IGroup::SummitAdministrators,
90+
IGroup::TrackChairsAdmins,
91+
IGroup::TrackChairs
92+
]
93+
],
94+
parameters: [
95+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
96+
new OA\Parameter(name: "page", description: "Page number", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 1)),
97+
new OA\Parameter(name: "per_page", description: "Items per page", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 10)),
98+
new OA\Parameter(name: "filter", description: "Filter query (member_first_name=@value, member_last_name=@value, member_email=@value, member_id==value, track_id==value)", in: "query", required: false, schema: new OA\Schema(type: "string")),
99+
new OA\Parameter(name: "order", description: "Order by (+member_first_name, -member_last_name, +member_email, +id, +track_id)", in: "query", required: false, schema: new OA\Schema(type: "string")),
100+
new OA\Parameter(name: "expand", description: "Expand relations (categories, member, summit)", in: "query", required: false, schema: new OA\Schema(type: "string")),
101+
new OA\Parameter(name: "relations", description: "Include relations (categories)", in: "query", required: false, schema: new OA\Schema(type: "string")),
102+
],
103+
responses: [
104+
new OA\Response(
105+
response: Response::HTTP_OK,
106+
description: "OK",
107+
content: new OA\JsonContent(ref: "#/components/schemas/PaginatedTrackChairsResponse")
108+
),
109+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
110+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
111+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
112+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
113+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
114+
]
115+
)]
76116
public function getAllBySummit($summit_id){
77117
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
78118
if (is_null($summit)) return $this->error404();
@@ -133,10 +173,51 @@ function () {
133173
);
134174
}
135175

136-
/**
137-
* @param $summit_id
138-
* @return mixed
139-
*/
176+
#[OA\Get(
177+
path: "/api/v1/summits/{id}/track-chairs/csv",
178+
summary: "Get all track chairs for a summit in CSV format",
179+
security: [['summit_track_chairs_oauth2' => [
180+
SummitScopes::ReadSummitData,
181+
SummitScopes::ReadAllSummitData,
182+
]]],
183+
tags: ["TrackChairs"],
184+
x: [
185+
'required-groups' => [
186+
IGroup::SuperAdmins,
187+
IGroup::Administrators,
188+
IGroup::SummitAdministrators,
189+
IGroup::TrackChairsAdmins
190+
]
191+
],
192+
parameters: [
193+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
194+
new OA\Parameter(name: "filter", description: "Filter query", in: "query", required: false, schema: new OA\Schema(type: "string")),
195+
new OA\Parameter(name: "order", description: "Order by", in: "query", required: false, schema: new OA\Schema(type: "string")),
196+
new OA\Parameter(
197+
name: "columns",
198+
description: "Comma-separated list of columns to export. Allowed: created,last_edited,member_first_name,member_last_name,member_email,member_id,categories,summit_id",
199+
in: "query",
200+
required: false,
201+
schema: new OA\Schema(type: "string"),
202+
example: "member_first_name,member_last_name,member_email,categories"
203+
),
204+
],
205+
responses: [
206+
new OA\Response(
207+
response: Response::HTTP_OK,
208+
description: "OK - CSV file download",
209+
content: new OA\MediaType(
210+
mediaType: "text/csv",
211+
schema: new OA\Schema(type: "string", format: "binary")
212+
)
213+
),
214+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
215+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
216+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
217+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
218+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
219+
]
220+
)]
140221
public function getAllBySummitCSV($summit_id){
141222

142223
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
@@ -294,12 +375,212 @@ protected function getChildFromSummit(Summit $summit, $child_id):?IEntity{
294375
return $summit->getTrackChair(intval($child_id));
295376
}
296377

297-
/**
298-
* @param $summit_id
299-
* @param $track_chair_id
300-
* @param $track_id
301-
* @return \Illuminate\Http\JsonResponse|mixed
302-
*/
378+
#[OA\Post(
379+
path: "/api/v1/summits/{id}/track-chairs",
380+
summary: "Add a track chair to a summit",
381+
security: [['summit_track_chairs_oauth2' => [
382+
SummitScopes::WriteSummitData,
383+
]]],
384+
tags: ["TrackChairs"],
385+
x: [
386+
'required-groups' => [
387+
IGroup::SuperAdmins,
388+
IGroup::Administrators,
389+
IGroup::SummitAdministrators,
390+
IGroup::TrackChairsAdmins
391+
]
392+
],
393+
parameters: [
394+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
395+
],
396+
requestBody: new OA\RequestBody(
397+
required: true,
398+
content: new OA\JsonContent(ref: "#/components/schemas/TrackChairAddRequest")
399+
),
400+
responses: [
401+
new OA\Response(
402+
response: Response::HTTP_CREATED,
403+
description: "Created",
404+
content: new OA\JsonContent(ref: "#/components/schemas/AdminSummitTrackChair")
405+
),
406+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
407+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
408+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
409+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
410+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
411+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
412+
]
413+
)]
414+
public function add($summit_id){
415+
return $this->processRequest(function() use($summit_id){
416+
$summit = SummitFinderStrategyFactory::build($this->getSummitRepository(), $this->getResourceServerContext())->find($summit_id);
417+
if (is_null($summit)) return $this->error404();
418+
return $this->_add($summit, $this->getJsonPayload($this->getAddValidationRules()));
419+
});
420+
}
421+
422+
#[OA\Get(
423+
path: "/api/v1/summits/{id}/track-chairs/{track_chair_id}",
424+
summary: "Get a track chair by id",
425+
security: [['summit_track_chairs_oauth2' => [
426+
SummitScopes::ReadSummitData,
427+
SummitScopes::ReadAllSummitData,
428+
]]],
429+
tags: ["TrackChairs"],
430+
x: [
431+
'required-groups' => [
432+
IGroup::SuperAdmins,
433+
IGroup::Administrators,
434+
IGroup::SummitAdministrators,
435+
IGroup::TrackChairsAdmins
436+
]
437+
],
438+
parameters: [
439+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
440+
new OA\Parameter(name: "track_chair_id", description: "Track chair ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
441+
new OA\Parameter(name: "expand", description: "Expand relations (categories, member, summit)", in: "query", required: false, schema: new OA\Schema(type: "string")),
442+
],
443+
responses: [
444+
new OA\Response(
445+
response: Response::HTTP_OK,
446+
description: "OK",
447+
content: new OA\JsonContent(
448+
oneOf: [
449+
new OA\Schema(ref: "#/components/schemas/SummitTrackChair"),
450+
new OA\Schema(ref: "#/components/schemas/AdminSummitTrackChair")
451+
]
452+
)
453+
),
454+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
455+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
456+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
457+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
458+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
459+
]
460+
)]
461+
public function get($summit_id, $track_chair_id){
462+
return $this->processRequest(function() use($summit_id, $track_chair_id){
463+
$summit = SummitFinderStrategyFactory::build($this->getSummitRepository(), $this->getResourceServerContext())->find($summit_id);
464+
if (is_null($summit)) return $this->error404();
465+
return $this->_get($summit, $track_chair_id);
466+
});
467+
}
468+
469+
#[OA\Put(
470+
path: "/api/v1/summits/{id}/track-chairs/{track_chair_id}",
471+
summary: "Update a track chair's categories",
472+
security: [['summit_track_chairs_oauth2' => [
473+
SummitScopes::WriteSummitData,
474+
]]],
475+
tags: ["TrackChairs"],
476+
x: [
477+
'required-groups' => [
478+
IGroup::SuperAdmins,
479+
IGroup::Administrators,
480+
IGroup::SummitAdministrators,
481+
IGroup::TrackChairsAdmins
482+
]
483+
],
484+
parameters: [
485+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
486+
new OA\Parameter(name: "track_chair_id", description: "Track chair ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
487+
],
488+
requestBody: new OA\RequestBody(
489+
required: true,
490+
content: new OA\JsonContent(ref: "#/components/schemas/TrackChairUpdateRequest")
491+
),
492+
responses: [
493+
new OA\Response(
494+
response: Response::HTTP_OK,
495+
description: "OK",
496+
content: new OA\JsonContent(ref: "#/components/schemas/AdminSummitTrackChair")
497+
),
498+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
499+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
500+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
501+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
502+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
503+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
504+
]
505+
)]
506+
public function update($summit_id, $track_chair_id){
507+
return $this->processRequest(function() use($summit_id, $track_chair_id){
508+
$summit = SummitFinderStrategyFactory::build($this->getSummitRepository(), $this->getResourceServerContext())->find($summit_id);
509+
if (is_null($summit)) return $this->error404();
510+
return $this->_update($summit, $track_chair_id, $this->getJsonPayload($this->getUpdateValidationRules()));
511+
});
512+
}
513+
514+
#[OA\Delete(
515+
path: "/api/v1/summits/{id}/track-chairs/{track_chair_id}",
516+
summary: "Delete a track chair",
517+
security: [['summit_track_chairs_oauth2' => [
518+
SummitScopes::WriteSummitData,
519+
]]],
520+
tags: ["TrackChairs"],
521+
x: [
522+
'required-groups' => [
523+
IGroup::SuperAdmins,
524+
IGroup::Administrators,
525+
IGroup::SummitAdministrators,
526+
IGroup::TrackChairsAdmins
527+
]
528+
],
529+
parameters: [
530+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
531+
new OA\Parameter(name: "track_chair_id", description: "Track chair ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
532+
],
533+
responses: [
534+
new OA\Response(response: Response::HTTP_NO_CONTENT, description: "No Content"),
535+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
536+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
537+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
538+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
539+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
540+
]
541+
)]
542+
public function delete($summit_id, $track_chair_id){
543+
return $this->processRequest(function() use($summit_id, $track_chair_id){
544+
$summit = SummitFinderStrategyFactory::build($this->getSummitRepository(), $this->getResourceServerContext())->find($summit_id);
545+
if (is_null($summit)) return $this->error404();
546+
return $this->_delete($summit, $track_chair_id);
547+
});
548+
}
549+
550+
#[OA\Post(
551+
path: "/api/v1/summits/{id}/track-chairs/{track_chair_id}/categories/{track_id}",
552+
summary: "Add a track/category to a track chair",
553+
security: [['summit_track_chairs_oauth2' => [
554+
SummitScopes::WriteSummitData,
555+
]]],
556+
tags: ["TrackChairs"],
557+
x: [
558+
'required-groups' => [
559+
IGroup::SuperAdmins,
560+
IGroup::Administrators,
561+
IGroup::SummitAdministrators,
562+
IGroup::TrackChairsAdmins
563+
]
564+
],
565+
parameters: [
566+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
567+
new OA\Parameter(name: "track_chair_id", description: "Track chair ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
568+
new OA\Parameter(name: "track_id", description: "Track/Category ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
569+
],
570+
responses: [
571+
new OA\Response(
572+
response: Response::HTTP_OK,
573+
description: "OK",
574+
content: new OA\JsonContent(ref: "#/components/schemas/AdminSummitTrackChair")
575+
),
576+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
577+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
578+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
579+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
580+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
581+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
582+
]
583+
)]
303584
public function addTrack2TrackChair($summit_id, $track_chair_id, $track_id){
304585
try{
305586
$summit = SummitFinderStrategyFactory::build($this->getSummitRepository(), $this->getResourceServerContext())->find($summit_id);
@@ -329,12 +610,40 @@ public function addTrack2TrackChair($summit_id, $track_chair_id, $track_id){
329610
}
330611
}
331612

332-
/**
333-
* @param $summit_id
334-
* @param $track_chair_id
335-
* @param $track_id
336-
* @return \Illuminate\Http\JsonResponse|mixed
337-
*/
613+
#[OA\Delete(
614+
path: "/api/v1/summits/{id}/track-chairs/{track_chair_id}/categories/{track_id}",
615+
summary: "Remove a track/category from a track chair",
616+
security: [['summit_track_chairs_oauth2' => [
617+
SummitScopes::WriteSummitData,
618+
]]],
619+
tags: ["TrackChairs"],
620+
x: [
621+
'required-groups' => [
622+
IGroup::SuperAdmins,
623+
IGroup::Administrators,
624+
IGroup::SummitAdministrators,
625+
IGroup::TrackChairsAdmins
626+
]
627+
],
628+
parameters: [
629+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
630+
new OA\Parameter(name: "track_chair_id", description: "Track chair ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
631+
new OA\Parameter(name: "track_id", description: "Track/Category ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
632+
],
633+
responses: [
634+
new OA\Response(
635+
response: Response::HTTP_OK,
636+
description: "OK",
637+
content: new OA\JsonContent(ref: "#/components/schemas/AdminSummitTrackChair")
638+
),
639+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
640+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
641+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
642+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
643+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
644+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
645+
]
646+
)]
338647
public function removeFromTrackChair($summit_id, $track_chair_id, $track_id){
339648
try{
340649
$summit = SummitFinderStrategyFactory::build($this->getSummitRepository(), $this->getResourceServerContext())->find($summit_id);

0 commit comments

Comments
 (0)