Skip to content

Commit 189390c

Browse files
andrestejerina97andrestejerina97
committed
feat: Add openapi documentation for OAuth2SummitBadgeScanApiController
1 parent 8a58d6d commit 189390c

File tree

3 files changed

+476
-21
lines changed

3 files changed

+476
-21
lines changed

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

Lines changed: 299 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@
1414
use App\Http\Exceptions\HTTP403ForbiddenException;
1515
use App\Http\Utils\EpochCellFormatter;
1616
use App\ModelSerializers\SerializerUtils;
17+
use App\Models\Foundation\Main\IGroup;
18+
use App\Security\SummitScopes;
1719
use App\Services\Model\IAttendeeService;
1820
use Illuminate\Support\Facades\Request;
1921
use Libs\ModelSerializers\AbstractSerializer;
@@ -28,6 +30,8 @@
2830
use models\summit\SummitOrderExtraQuestionTypeConstants;
2931
use models\utils\IEntity;
3032
use ModelSerializers\SerializerRegistry;
33+
use OpenApi\Attributes as OA;
34+
use Symfony\Component\HttpFoundation\Response;
3135
use utils\Filter;
3236
use utils\FilterElement;
3337
/**
@@ -146,11 +150,31 @@ protected function updateChild(Summit $summit,int $child_id, array $payload):IEn
146150
return $this->service->updateBadgeScan($summit, $current_member, $child_id, $payload);
147151
}
148152

149-
/**
150-
* @param $summit_id
151-
* @param $sponsor_id
152-
* @return \Illuminate\Http\JsonResponse|mixed
153-
*/
153+
#[OA\Post(
154+
path: "/api/v1/summits/{id}/sponsors/{sponsor_id}/user-info-grants/me",
155+
summary: "Add user info grant for current user",
156+
operationId: "addUserInfoWithSponsor",
157+
tags: ["SponsorUserInfoGrants"],
158+
security: [['summit_badge_scan_oauth2' => [
159+
SummitScopes::WriteMyBadgeScan,
160+
]]],
161+
parameters: [
162+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
163+
new OA\Parameter(name: "sponsor_id", description: "Sponsor ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
164+
],
165+
responses: [
166+
new OA\Response(
167+
response: Response::HTTP_CREATED,
168+
description: "Created",
169+
content: new OA\JsonContent(ref: "#/components/schemas/SponsorUserInfoGrant")
170+
),
171+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
172+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
173+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
174+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
175+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
176+
]
177+
)]
154178
public function addGrant($summit_id, $sponsor_id){
155179
return $this->processRequest(function() use($summit_id, $sponsor_id){
156180
$summit = SummitFinderStrategyFactory::build($this->getSummitRepository(), $this->getResourceServerContext())->find($summit_id);
@@ -183,10 +207,34 @@ protected function getSummitRepository(): ISummitRepository
183207
// traits
184208
use ParametrizedGetAll;
185209

186-
/**
187-
* @param $summit_id
188-
* @return \Illuminate\Http\JsonResponse|mixed
189-
*/
210+
#[OA\Get(
211+
path: "/api/v1/summits/{id}/badge-scans/me",
212+
summary: "Get all my badge scans for a summit",
213+
operationId: "getMyBadgeScans",
214+
tags: ['BadgeScans'],
215+
security: [['summit_badge_scan_oauth2' => [
216+
SummitScopes::ReadMyBadgeScan,
217+
]]],
218+
parameters: [
219+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
220+
new OA\Parameter(name: "page", description: "Page number", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 1)),
221+
new OA\Parameter(name: "per_page", description: "Items per page", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 10)),
222+
new OA\Parameter(name: "filter", description: "Filter query", in: "query", required: false, schema: new OA\Schema(type: "string")),
223+
new OA\Parameter(name: "order", description: "Order by", in: "query", required: false, schema: new OA\Schema(type: "string")),
224+
],
225+
responses: [
226+
new OA\Response(
227+
response: Response::HTTP_OK,
228+
description: "OK",
229+
content: new OA\JsonContent(ref: "#/components/schemas/PaginatedBadgeScansResponse")
230+
),
231+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
232+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
233+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
234+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
235+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
236+
]
237+
)]
190238
public function getAllMyBadgeScans($summit_id){
191239
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
192240
if (is_null($summit))
@@ -238,10 +286,44 @@ function(){
238286
);
239287
}
240288

241-
/**
242-
* @param $summit_id
243-
* @return mixed
244-
*/
289+
#[OA\Get(
290+
path: "/api/v1/summits/{id}/badge-scans",
291+
summary: "Get all badge scans for a summit",
292+
operationId: "getAllBadgeScans",
293+
tags: ['BadgeScans'],
294+
x: [
295+
'required-groups' => [
296+
IGroup::SummitAdministrators,
297+
IGroup::SuperAdmins,
298+
IGroup::Administrators,
299+
IGroup::Sponsors,
300+
IGroup::SponsorExternalUsers,
301+
]
302+
],
303+
security: [['summit_badge_scan_oauth2' => [
304+
SummitScopes::ReadAllSummitData,
305+
SummitScopes::ReadBadgeScan,
306+
]]],
307+
parameters: [
308+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
309+
new OA\Parameter(name: "page", description: "Page number", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 1)),
310+
new OA\Parameter(name: "per_page", description: "Items per page", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 10)),
311+
new OA\Parameter(name: "filter", description: "Filter query", in: "query", required: false, schema: new OA\Schema(type: "string")),
312+
new OA\Parameter(name: "order", description: "Order by", in: "query", required: false, schema: new OA\Schema(type: "string")),
313+
],
314+
responses: [
315+
new OA\Response(
316+
response: Response::HTTP_OK,
317+
description: "OK",
318+
content: new OA\JsonContent(ref: "#/components/schemas/PaginatedBadgeScansResponse")
319+
),
320+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
321+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
322+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
323+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
324+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
325+
]
326+
)]
245327
public function getAllBySummit($summit_id){
246328

247329
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
@@ -322,10 +404,46 @@ function(){
322404
);
323405
}
324406

325-
/**
326-
* @param $summit_id
327-
* @return mixed
328-
*/
407+
#[OA\Get(
408+
path: "/api/v1/summits/{id}/badge-scans/csv",
409+
summary: "Get all badge scans for a summit in CSV format",
410+
operationId: "getAllBadgeScansCSV",
411+
tags: ['BadgeScans'],
412+
x: [
413+
'required-groups' => [
414+
IGroup::SummitAdministrators,
415+
IGroup::SuperAdmins,
416+
IGroup::Administrators,
417+
IGroup::Sponsors,
418+
IGroup::SponsorExternalUsers,
419+
]
420+
],
421+
security: [['summit_badge_scan_oauth2' => [
422+
SummitScopes::ReadAllSummitData,
423+
SummitScopes::ReadBadgeScan,
424+
]]],
425+
parameters: [
426+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
427+
new OA\Parameter(name: "filter", description: "Filter query", in: "query", required: false, schema: new OA\Schema(type: "string")),
428+
new OA\Parameter(name: "order", description: "Order by", in: "query", required: false, schema: new OA\Schema(type: "string")),
429+
new OA\Parameter(name: "columns", description: "Columns to export (comma separated)", in: "query", required: false, schema: new OA\Schema(type: "string")),
430+
],
431+
responses: [
432+
new OA\Response(
433+
response: Response::HTTP_OK,
434+
description: "OK",
435+
content: new OA\MediaType(
436+
mediaType: "text/csv",
437+
schema: new OA\Schema(type: "string", format: "binary")
438+
)
439+
),
440+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
441+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
442+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
443+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
444+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
445+
]
446+
)]
329447
public function getAllBySummitCSV($summit_id){
330448

331449
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
@@ -457,10 +575,78 @@ function() use($summit) {
457575
);
458576
}
459577

460-
/**
461-
* @param $summit_id
462-
* @return mixed
463-
*/
578+
#[OA\Post(
579+
path: "/api/v1/summits/{id}/badge-scans",
580+
summary: "Add a badge scan",
581+
operationId: "addBadgeScan",
582+
tags: ['BadgeScans'],
583+
x: [
584+
'required-groups' => [
585+
IGroup::SummitAdministrators,
586+
IGroup::SuperAdmins,
587+
IGroup::Administrators,
588+
IGroup::Sponsors,
589+
IGroup::SponsorExternalUsers,
590+
]
591+
],
592+
security: [['summit_badge_scan_oauth2' => [
593+
SummitScopes::WriteBadgeScan,
594+
]]],
595+
parameters: [
596+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
597+
],
598+
requestBody: new OA\RequestBody(
599+
required: true,
600+
content: new OA\JsonContent(ref: "#/components/schemas/BadgeScanAddRequest")
601+
),
602+
responses: [
603+
new OA\Response(
604+
response: Response::HTTP_CREATED,
605+
description: "Created",
606+
content: new OA\JsonContent(ref: "#/components/schemas/SponsorBadgeScan")
607+
),
608+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
609+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
610+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
611+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
612+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
613+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
614+
]
615+
)]
616+
public function add($summit_id){
617+
return $this->processRequest(function() use($summit_id){
618+
$summit = SummitFinderStrategyFactory::build($this->getSummitRepository(), $this->getResourceServerContext())->find($summit_id);
619+
if (is_null($summit)) return $this->error404();
620+
return $this->_add($summit, $this->getJsonPayload($this->getAddValidationRules()));
621+
});
622+
}
623+
624+
#[OA\Put(
625+
path: "/api/v1/summits/{id}/badge-scans/checkin",
626+
summary: "Check in an attendee using QR code",
627+
operationId: "checkInBadgeScan",
628+
tags: ['BadgeScans'],
629+
security: [['summit_badge_scan_oauth2' => [
630+
SummitScopes::WriteBadgeScan,
631+
SummitScopes::WriteSummitData,
632+
]]],
633+
parameters: [
634+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
635+
],
636+
requestBody: new OA\RequestBody(
637+
required: true,
638+
content: new OA\JsonContent(ref: "#/components/schemas/BadgeScanCheckInRequest")
639+
),
640+
responses: [
641+
new OA\Response(response: Response::HTTP_OK, description: "OK"),
642+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
643+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
644+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
645+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
646+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
647+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
648+
]
649+
)]
464650
protected function checkIn($summit_id) {
465651
return $this->processRequest(function () use ($summit_id) {
466652
if(!Request::isJson()) return $this->error400();
@@ -488,4 +674,96 @@ protected function getChildFromSummit(Summit $summit, $child_id): ?IEntity
488674

489675
return $this->service->getBadgeScan($summit, $current_member, $child_id);
490676
}
677+
678+
#[OA\Get(
679+
path: "/api/v1/summits/{id}/badge-scans/{scan_id}",
680+
summary: "Get a badge scan by id",
681+
operationId: "getBadgeScan",
682+
tags: ['BadgeScans'],
683+
x: [
684+
'required-groups' => [
685+
IGroup::SummitAdministrators,
686+
IGroup::SuperAdmins,
687+
IGroup::Administrators,
688+
IGroup::Sponsors,
689+
IGroup::SponsorExternalUsers,
690+
]
691+
],
692+
security: [['summit_badge_scan_oauth2' => [
693+
SummitScopes::ReadAllSummitData,
694+
SummitScopes::ReadBadgeScan,
695+
SummitScopes::ReadMyBadgeScan,
696+
]]],
697+
parameters: [
698+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
699+
new OA\Parameter(name: "scan_id", description: "Badge scan ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
700+
],
701+
responses: [
702+
new OA\Response(
703+
response: Response::HTTP_OK,
704+
description: "OK",
705+
content: new OA\JsonContent(ref: "#/components/schemas/SponsorBadgeScan")
706+
),
707+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
708+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
709+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
710+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
711+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
712+
]
713+
)]
714+
public function get($summit_id, $scan_id){
715+
return $this->processRequest(function() use($summit_id, $scan_id){
716+
$summit = SummitFinderStrategyFactory::build($this->getSummitRepository(), $this->getResourceServerContext())->find($summit_id);
717+
if (is_null($summit)) return $this->error404();
718+
return $this->_get($summit, $scan_id);
719+
});
720+
}
721+
722+
#[OA\Put(
723+
path: "/api/v1/summits/{id}/badge-scans/{scan_id}",
724+
summary: "Update a badge scan",
725+
operationId: "updateBadgeScan",
726+
tags: ['BadgeScans'],
727+
x: [
728+
'required-groups' => [
729+
IGroup::SummitAdministrators,
730+
IGroup::SuperAdmins,
731+
IGroup::Administrators,
732+
IGroup::Sponsors,
733+
IGroup::SponsorExternalUsers,
734+
]
735+
],
736+
security: [['summit_badge_scan_oauth2' => [
737+
SummitScopes::WriteSummitData,
738+
SummitScopes::WriteBadgeScan,
739+
]]],
740+
parameters: [
741+
new OA\Parameter(name: "id", description: "Summit ID or slug", in: "path", required: true, schema: new OA\Schema(type: "string")),
742+
new OA\Parameter(name: "scan_id", description: "Badge scan ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
743+
],
744+
requestBody: new OA\RequestBody(
745+
required: true,
746+
content: new OA\JsonContent(ref: "#/components/schemas/BadgeScanUpdateRequest")
747+
),
748+
responses: [
749+
new OA\Response(
750+
response: Response::HTTP_OK,
751+
description: "OK",
752+
content: new OA\JsonContent(ref: "#/components/schemas/SponsorBadgeScan")
753+
),
754+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
755+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
756+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
757+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"),
758+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
759+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
760+
]
761+
)]
762+
public function update($summit_id, $scan_id){
763+
return $this->processRequest(function() use($summit_id, $scan_id){
764+
$summit = SummitFinderStrategyFactory::build($this->getSummitRepository(), $this->getResourceServerContext())->find($summit_id);
765+
if (is_null($summit)) return $this->error404();
766+
return $this->_update($summit, $scan_id, $this->getJsonPayload($this->getUpdateValidationRules()));
767+
});
768+
}
491769
}

0 commit comments

Comments
 (0)