From 792b6d0081ec2a98e6834653ccf7a0c706669875 Mon Sep 17 00:00:00 2001 From: Matias Perrone Date: Tue, 14 Oct 2025 15:19:33 -0300 Subject: [PATCH] feat: Extend Swagger Coverage for controller `OAuth2SummitSubmissionInvitationApiController` --- ...ummitSubmissionInvitationApiController.php | 420 ++++++++++++++++-- app/Swagger/SummitSpeakersSchemas.php | 127 ++++++ 2 files changed, 517 insertions(+), 30 deletions(-) diff --git a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmissionInvitationApiController.php b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmissionInvitationApiController.php index c1016741b..3503f32c1 100644 --- a/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmissionInvitationApiController.php +++ b/app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitSubmissionInvitationApiController.php @@ -1,4 +1,7 @@ -service = $service; } - /** - * @param LaravelRequest $request - * @param $summit_id - * @return \Illuminate\Http\JsonResponse|mixed - */ + #[OA\Post( + path: "/api/v1/summits/{id}/submission-invitations/csv", + description: "Import submission invitations from CSV file", + summary: "Import submission invitations from CSV", + operationId: "ingestSummitSubmissionInvitations", + tags: ['Summit Submission Invitations'], + security: [['summit_oauth2' => []]], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + schema: new OA\Schema(type: 'integer'), + description: 'The summit id' + ) + ], + requestBody: new OA\RequestBody( + required: true, + content: new OA\MediaType( + mediaType: 'multipart/form-data', + schema: new OA\Schema( + type: 'object', + required: ['file'], + properties: [ + new OA\Property( + property: 'file', + type: 'string', + format: 'binary', + description: 'CSV file to import' + ) + ] + ) + ) + ), + responses: [ + new OA\Response(response: 200, description: 'Success'), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"), + new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error") + ] + )] public function ingestInvitations(LaravelRequest $request, $summit_id) { return $this->processRequest(function () use ($request, $summit_id) { @@ -94,11 +155,6 @@ public function ingestInvitations(LaravelRequest $request, $summit_id) }); } - // traits - use ParametrizedGetAll; - - use GetSummitChildElementById; - /** * @return ISummitRepository */ @@ -115,10 +171,77 @@ protected function getChildFromSummit(Summit $summit, $child_id): ?IEntity return $summit->getSubmissionInvitationById($child_id); } - /** - * @param $summit_id - * @return mixed - */ + #[OA\Get( + path: "/api/v1/summits/{id}/submission-invitations", + description: "Get all submission invitations for a summit", + summary: "Get all submission invitations", + operationId: "getAllSummitSubmissionInvitations", + tags: ['Summit Submission Invitations'], + security: [['summit_oauth2' => []]], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + schema: new OA\Schema(type: 'integer'), + description: 'The summit id' + ), + new OA\Parameter( + name: 'page', + in: 'query', + required: false, + schema: new OA\Schema(type: 'integer', default: 1), + description: 'Page number' + ), + new OA\Parameter( + name: 'per_page', + in: 'query', + required: false, + schema: new OA\Schema(type: 'integer', default: 10), + description: 'Items per page' + ), + new OA\Parameter( + name: 'filter', + in: 'query', + required: false, + schema: new OA\Schema(type: 'string'), + description: 'Filter expression (e.g., email=@john,is_sent==true)' + ), + new OA\Parameter( + name: 'order', + in: 'query', + required: false, + schema: new OA\Schema(type: 'string'), + description: 'Order by field (e.g., +id, -email)' + ), + new OA\Parameter( + name: 'expand', + in: 'query', + required: false, + schema: new OA\Schema(type: 'string'), + description: 'Expand relationships (tags)' + ), + new OA\Parameter( + name: 'relations', + in: 'query', + required: false, + schema: new OA\Schema(type: 'string'), + description: 'Relations to include (tags)' + ) + ], + responses: [ + new OA\Response( + response: 200, + description: 'Success', + content: new OA\JsonContent(ref: '#/components/schemas/PaginatedSummitSubmissionInvitationsResponse') + ), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"), + new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error") + ] + )] public function getAllBySummit($summit_id) { @@ -169,10 +292,59 @@ function () { ); } - /** - * @param $summit_id - * @return mixed - */ + #[OA\Get( + path: "/api/v1/summits/{id}/submission-invitations/csv", + description: "Get all submission invitations for a summit in CSV format", + summary: "Get all submission invitations (CSV)", + operationId: "getAllSummitSubmissionInvitationsCSV", + tags: ['Summit Submission Invitations'], + security: [['summit_oauth2' => []]], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + schema: new OA\Schema(type: 'integer'), + description: 'The summit id' + ), + new OA\Parameter( + name: 'filter', + in: 'query', + required: false, + schema: new OA\Schema(type: 'string'), + description: 'Filter expression' + ), + new OA\Parameter( + name: 'order', + in: 'query', + required: false, + schema: new OA\Schema(type: 'string'), + description: 'Order by field' + ), + new OA\Parameter( + name: 'columns', + in: 'query', + required: false, + schema: new OA\Schema(type: 'string'), + description: 'Comma-separated list of columns to include' + ) + ], + responses: [ + new OA\Response( + response: 200, + description: 'Success', + content: new OA\MediaType( + mediaType: 'text/csv', + schema: new OA\Schema(type: 'string', format: 'binary') + ) + ), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"), + new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error") + ] + )] public function getAllBySummitCSV($summit_id) { @@ -255,9 +427,6 @@ function () { ); } - - use DeleteSummitChildElement; - /** * @inheritDoc */ @@ -266,8 +435,6 @@ protected function deleteChild(Summit $summit, $child_id): void $this->service->delete($summit, $child_id); } - use AddSummitChildElement; - /** * @inheritDoc */ @@ -284,8 +451,6 @@ function getAddValidationRules(array $payload): array return SummitSubmissionInvitationValidationRulesFactory::buildForAdd($payload); } - use UpdateSummitChildElement; - /** * @inheritDoc */ @@ -302,10 +467,205 @@ protected function updateChild(Summit $summit, int $child_id, array $payload): I return $this->service->update($summit, $child_id, $payload); } - /** - * @param $summit_id - * @return \Illuminate\Http\JsonResponse|mixed - */ + #[OA\Get( + path: "/api/v1/summits/{id}/submission-invitations/{invitation_id}", + description: "Get a specific submission invitation by id", + summary: "Get submission invitation", + operationId: "getSummitSubmissionInvitation", + tags: ['Summit Submission Invitations'], + security: [['summit_oauth2' => []]], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + schema: new OA\Schema(type: 'integer'), + description: 'The summit id' + ), + new OA\Parameter( + name: 'invitation_id', + in: 'path', + required: true, + schema: new OA\Schema(type: 'integer'), + description: 'The invitation id' + ), + new OA\Parameter( + name: 'expand', + in: 'query', + required: false, + schema: new OA\Schema(type: 'string'), + description: 'Expand relationships (tags)' + ), + new OA\Parameter( + name: 'relations', + in: 'query', + required: false, + schema: new OA\Schema(type: 'string'), + description: 'Relations to include (tags)' + ) + ], + responses: [ + new OA\Response( + response: 200, + description: 'Success', + content: new OA\JsonContent(ref: '#/components/schemas/SummitSubmissionInvitation') + ), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error") + ] + )] + public function get($summit_id, $invitation_id) + { + return $this->traitGet($summit_id, $invitation_id); + } + + #[OA\Post( + path: "/api/v1/summits/{id}/submission-invitations", + description: "Create a new submission invitation", + summary: "Create submission invitation", + operationId: "createSummitSubmissionInvitation", + tags: ['Summit Submission Invitations'], + security: [['summit_oauth2' => []]], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + schema: new OA\Schema(type: 'integer'), + description: 'The summit id' + ) + ], + requestBody: new OA\RequestBody( + required: true, + content: new OA\JsonContent(ref: '#/components/schemas/SummitSubmissionInvitationCreateRequest') + ), + responses: [ + new OA\Response( + response: 201, + description: 'Created', + content: new OA\JsonContent(ref: '#/components/schemas/SummitSubmissionInvitation') + ), + new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"), + new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error") + ] + )] + public function add($summit_id) + { + return $this->traitAdd($summit_id); + } + + #[OA\Put( + path: "/api/v1/summits/{id}/submission-invitations/{invitation_id}", + description: "Update an existing submission invitation", + summary: "Update submission invitation", + operationId: "updateSummitSubmissionInvitation", + tags: ['Summit Submission Invitations'], + security: [['summit_oauth2' => []]], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + schema: new OA\Schema(type: 'integer'), + description: 'The summit id' + ), + new OA\Parameter( + name: 'invitation_id', + in: 'path', + required: true, + schema: new OA\Schema(type: 'integer'), + description: 'The invitation id' + ) + ], + requestBody: new OA\RequestBody( + required: true, + content: new OA\JsonContent(ref: '#/components/schemas/SummitSubmissionInvitationUpdateRequest') + ), + responses: [ + new OA\Response( + response: 200, + description: 'Success', + content: new OA\JsonContent(ref: '#/components/schemas/SummitSubmissionInvitation') + ), + new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"), + new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error") + ] + )] + public function update($summit_id, $invitation_id) + { + return $this->traitUpdate($summit_id, $invitation_id); + } + + #[OA\Delete( + path: "/api/v1/summits/{id}/submission-invitations/{invitation_id}", + description: "Delete a submission invitation", + summary: "Delete submission invitation", + operationId: "deleteSummitSubmissionInvitation", + tags: ['Summit Submission Invitations'], + security: [['summit_oauth2' => []]], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + schema: new OA\Schema(type: 'integer'), + description: 'The summit id' + ), + new OA\Parameter( + name: 'invitation_id', + in: 'path', + required: true, + schema: new OA\Schema(type: 'integer'), + description: 'The invitation id' + ) + ], + responses: [ + new OA\Response(response: 204, description: 'No Content'), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error") + ] + )] + public function delete($summit_id, $invitation_id) + { + return $this->traitDelete($summit_id, $invitation_id); + } + + #[OA\Delete( + path: "/api/v1/summits/{id}/submission-invitations/all", + description: "Delete all submission invitations for a summit", + summary: "Delete all submission invitations", + operationId: "deleteAllSummitSubmissionInvitations", + tags: ['Summit Submission Invitations'], + security: [['summit_oauth2' => []]], + parameters: [ + new OA\Parameter( + name: 'id', + in: 'path', + required: true, + schema: new OA\Schema(type: 'integer'), + description: 'The summit id' + ) + ], + responses: [ + new OA\Response(response: 204, description: 'No Content'), + new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"), + new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "not found"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error") + ] + )] public function deleteAll($summit_id) { return $this->processRequest(function () use ($summit_id) { diff --git a/app/Swagger/SummitSpeakersSchemas.php b/app/Swagger/SummitSpeakersSchemas.php index 6b3e2f895..c812d4270 100644 --- a/app/Swagger/SummitSpeakersSchemas.php +++ b/app/Swagger/SummitSpeakersSchemas.php @@ -2,6 +2,133 @@ namespace App\Swagger\schemas; +use App\Jobs\Emails\PresentationSubmissions\Invitations\InviteSubmissionEmail; +use App\Jobs\Emails\PresentationSubmissions\Invitations\ReInviteSubmissionEmail; use OpenApi\Attributes as OA; +#[OA\Schema( + schema: 'SummitSubmissionInvitation', + type: 'object', + properties: [ + new OA\Property(property: 'id', type: 'integer', example: 1), + new OA\Property(property: 'created', type: 'integer', description: 'Unix timestamp', example: 1640995200), + new OA\Property(property: 'last_edited', type: 'integer', description: 'Unix timestamp', example: 1640995200), + new OA\Property(property: 'email', type: 'string', format: 'email', example: 'speaker@example.com'), + new OA\Property(property: 'first_name', type: 'string', example: 'John'), + new OA\Property(property: 'last_name', type: 'string', example: 'Doe'), + new OA\Property(property: 'summit_id', type: 'integer', example: 1), + new OA\Property(property: 'is_sent', type: 'boolean', example: false), + new OA\Property(property: 'sent_date', type: 'integer', description: 'Unix timestamp', example: 1640995200, nullable: true), + new OA\Property( + property: 'tags', + type: 'array', + items: new OA\Items(type: 'integer'), + example: [1, 2, 3] + ) + ] +)] +class SummitSubmissionInvitationSchema {} + +#[OA\Schema( + schema: 'PaginatedSummitSubmissionInvitationsResponse', + allOf: [ + new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'), + new OA\Schema( + type: 'object', + properties: [ + new OA\Property( + property: 'data', + type: 'array', + items: new OA\Items(ref: '#/components/schemas/SummitSubmissionInvitation') + ) + ] + ) + ] +)] +class PaginatedSummitSubmissionInvitationsResponseSchema {} + +#[OA\Schema( + schema: 'SummitSubmissionInvitationCSV', + type: 'object', + properties: [ + new OA\Property(property: 'id', type: 'integer', example: 1), + new OA\Property(property: 'email', type: 'string', format: 'email', example: 'speaker@example.com'), + new OA\Property(property: 'first_name', type: 'string', example: 'John'), + new OA\Property(property: 'last_name', type: 'string', example: 'Doe'), + new OA\Property(property: 'speaker_id', type: 'integer', nullable: true, example: 123), + new OA\Property(property: 'summit_id', type: 'integer', example: 1), + new OA\Property(property: 'is_sent', type: 'boolean', example: false), + new OA\Property(property: 'sent_date', type: 'integer', description: 'Unix timestamp', nullable: true, example: 1640995200), + new OA\Property(property: 'tags', type: 'string', example: 'tag1,tag2,tag3') + ] +)] +class SummitSubmissionInvitationCSVSchema {} + +#[OA\Schema( + schema: 'SummitSubmissionInvitationCreateRequest', + type: 'object', + required: ['email', 'first_name', 'last_name'], + properties: [ + new OA\Property(property: 'email', type: 'string', format: 'email', example: 'speaker@example.com'), + new OA\Property(property: 'first_name', type: 'string', example: 'John'), + new OA\Property(property: 'last_name', type: 'string', example: 'Doe'), + new OA\Property( + property: 'tags', + type: 'array', + items: new OA\Items(type: 'string'), + example: ['tag1', 'tag2'], + nullable: true + ) + ] +)] +class SummitSubmissionInvitationCreateRequestSchema {} + +#[OA\Schema( + schema: 'SummitSubmissionInvitationUpdateRequest', + type: 'object', + properties: [ + new OA\Property(property: 'email', type: 'string', format: 'email', example: 'speaker@example.com', nullable: true), + new OA\Property(property: 'first_name', type: 'string', example: 'John', nullable: true), + new OA\Property(property: 'last_name', type: 'string', example: 'Doe', nullable: true), + new OA\Property( + property: 'tags', + type: 'array', + items: new OA\Items(type: 'string'), + example: ['tag1', 'tag2'], + nullable: true + ) + ] +)] +class SummitSubmissionInvitationUpdateRequestSchema {} + +#[OA\Schema( + schema: 'SendSummitSubmissionInvitationsRequest', + type: 'object', + required: ['email_flow_event'], + properties: [ + new OA\Property( + property: 'email_flow_event', + type: 'string', + enum: [InviteSubmissionEmail::EVENT_SLUG, ReInviteSubmissionEmail::EVENT_SLUG], + example: InviteSubmissionEmail::EVENT_SLUG + ), + new OA\Property(property: 'selection_plan_id', type: 'integer', example: 1, nullable: true), + new OA\Property( + property: 'invitations_ids', + type: 'array', + items: new OA\Items(type: 'integer'), + example: [1, 2, 3], + nullable: true + ), + new OA\Property( + property: 'excluded_invitations_ids', + type: 'array', + items: new OA\Items(type: 'integer'), + example: [4, 5], + nullable: true + ) + ] +)] +class SendSummitSubmissionInvitationsRequestSchema {} + //