Skip to content

Commit 404d652

Browse files
andrestejerina97matiasperrone
andrestejerina97
and
matiasperrone
authored
Feature | Extend Swagger Coverage for controller OAuth2SummitAttendeeNotesApiController (#417)
* feat: Add openapi documentation for OAuth2SummitAttendeeNotesApiController * chore: include PR requested changes * chore: Rewrite schema structure --------- Co-authored-by: Matias Perrone <[email protected]>
1 parent a9e5e57 commit 404d652

File tree

5 files changed

+334
-38
lines changed

5 files changed

+334
-38
lines changed

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

Lines changed: 237 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,17 @@
1313
**/
1414

1515
use App\Http\Utils\EpochCellFormatter;
16+
use App\Models\Foundation\Main\IGroup;
1617
use App\Models\Foundation\Summit\Repositories\ISummitAttendeeNoteRepository;
1718
use App\ModelSerializers\SerializerUtils;
19+
use App\Security\SummitScopes;
1820
use App\Services\Model\IAttendeeService;
1921
use models\oauth2\IResourceServerContext;
2022
use models\summit\ISummitAttendeeRepository;
2123
use models\summit\ISummitRepository;
2224
use ModelSerializers\SerializerRegistry;
25+
use OpenApi\Attributes as OA;
26+
use Symfony\Component\HttpFoundation\Response;
2327
use utils\Filter;
2428
use utils\FilterElement;
2529

@@ -74,6 +78,35 @@ public function __construct
7478
$this->attendee_service = $attendee_service;
7579
}
7680

81+
#[OA\Get(
82+
path: "/api/v1/summits/{id}/attendees/all/notes",
83+
summary: "Get all attendee notes for a summit",
84+
description: "Returns all notes for all attendees in the summit. Admin access required.",
85+
operationId: 'getAllAttendeeNotes',
86+
tags: ["Attendee Notes"],
87+
security: [['summit_attendee_notes_oauth2' => [
88+
SummitScopes::ReadAllSummitData,
89+
SummitScopes::ReadAttendeeNotesData,
90+
]]],
91+
parameters: [
92+
new OA\Parameter(name: "id", description: "Summit ID", in: "path", required: true, schema: new OA\Schema(type: "string")),
93+
new OA\Parameter(name: "page", description: "Page number", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 1)),
94+
new OA\Parameter(name: "per_page", description: "Items per page", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 10)),
95+
new OA\Parameter(name: "filter", description: "Filter query", in: "query", required: false, schema: new OA\Schema(type: "string")),
96+
new OA\Parameter(name: "order", description: "Order by", in: "query", required: false, schema: new OA\Schema(type: "string")),
97+
new OA\Parameter(name: "expand", description: "Expand relations (author, owner, ticket)", in: "query", required: false, schema: new OA\Schema(type: "string")),
98+
],
99+
responses: [
100+
new OA\Response(
101+
response: Response::HTTP_OK,
102+
description: "OK",
103+
content: new OA\JsonContent(ref: "#/components/schemas/PaginatedAttendeeNotesResponse")
104+
),
105+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
106+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
107+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
108+
]
109+
)]
77110
/**
78111
* @param $summit_id
79112
* @return mixed
@@ -133,10 +166,30 @@ function () {
133166
);
134167
}
135168

136-
/**
137-
* @param $summit_id
138-
* @return mixed
139-
*/
169+
#[OA\Get(
170+
path: "/api/v1/summits/{id}/attendees/all/notes/csv",
171+
summary: "Export all attendee notes in CSV format",
172+
operationId: 'getAllAttendeeNotesCSV',
173+
security: [['summit_attendee_notes_oauth2' => [
174+
SummitScopes::ReadAllSummitData,
175+
SummitScopes::ReadAttendeeNotesData,
176+
]]],
177+
tags: ["Attendee Notes"],
178+
parameters: [
179+
new OA\Parameter(name: "id", description: "Summit ID", in: "path", required: true, schema: new OA\Schema(type: "string")),
180+
new OA\Parameter(name: "filter", description: "Filter query", in: "query", required: false, schema: new OA\Schema(type: "string")),
181+
new OA\Parameter(name: "order", description: "Order by", in: "query", required: false, schema: new OA\Schema(type: "string")),
182+
],
183+
responses: [
184+
new OA\Response(
185+
response: Response::HTTP_OK,
186+
description: "CSV file download",
187+
content: new OA\MediaType(mediaType: "text/csv", schema: new OA\Schema(type: "string", format: "binary"))
188+
),
189+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
190+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
191+
]
192+
)]
140193
public function getAllAttendeeNotesCSV($summit_id)
141194
{
142195
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
@@ -202,11 +255,33 @@ function () {
202255
);
203256
}
204257

205-
/**
206-
* @param $summit_id
207-
* @param $attendee_id
208-
* @return mixed
209-
*/
258+
#[OA\Get(
259+
path: "/api/v1/summits/{id}/attendees/{attendee_id}/notes",
260+
summary: "Get all notes for a specific attendee",
261+
operationId: 'getAttendeeNotes',
262+
security: [['summit_attendee_notes_oauth2' => [
263+
SummitScopes::ReadAllSummitData,
264+
SummitScopes::ReadAttendeeNotesData,
265+
]]],
266+
tags: ["Attendee Notes"],
267+
parameters: [
268+
new OA\Parameter(name: "id", description: "Summit ID", in: "path", required: true, schema: new OA\Schema(type: "string")),
269+
new OA\Parameter(name: "attendee_id", description: "Attendee ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
270+
new OA\Parameter(name: "page", description: "Page number", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 1)),
271+
new OA\Parameter(name: "per_page", description: "Items per page", in: "query", required: false, schema: new OA\Schema(type: "integer", default: 10)),
272+
new OA\Parameter(name: "expand", description: "Expand relations (author, owner, ticket)", in: "query", required: false, schema: new OA\Schema(type: "string")),
273+
],
274+
responses: [
275+
new OA\Response(
276+
response: Response::HTTP_OK,
277+
description: "OK",
278+
content: new OA\JsonContent(ref: "#/components/schemas/PaginatedAttendeeNotesResponse")
279+
),
280+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
281+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
282+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
283+
]
284+
)]
210285
public function getAttendeeNotes($summit_id, $attendee_id)
211286
{
212287
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
@@ -260,11 +335,29 @@ function () {
260335
);
261336
}
262337

263-
/**
264-
* @param $summit_id
265-
* @param $attendee_id
266-
* @return mixed
267-
*/
338+
#[OA\Get(
339+
path: "/api/v1/summits/{id}/attendees/{attendee_id}/notes/csv",
340+
summary: "Export notes for a specific attendee in CSV format",
341+
operationId: 'getAttendeeNotesCSV',
342+
security: [['summit_attendee_notes_oauth2' => [
343+
SummitScopes::ReadAllSummitData,
344+
SummitScopes::ReadAttendeeNotesData,
345+
]]],
346+
tags: ["Attendee Notes"],
347+
parameters: [
348+
new OA\Parameter(name: "id", description: "Summit ID", in: "path", required: true, schema: new OA\Schema(type: "string")),
349+
new OA\Parameter(name: "attendee_id", description: "Attendee ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
350+
],
351+
responses: [
352+
new OA\Response(
353+
response: Response::HTTP_OK,
354+
description: "CSV file download",
355+
content: new OA\MediaType(mediaType: "text/csv", schema: new OA\Schema(type: "string", format: "binary"))
356+
),
357+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
358+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
359+
]
360+
)]
268361
public function getAttendeeNotesCSV($summit_id, $attendee_id)
269362
{
270363
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->getResourceServerContext())->find($summit_id);
@@ -328,12 +421,32 @@ function () {
328421
);
329422
}
330423

331-
/**
332-
* @param $summit_id
333-
* @param $attendee_id
334-
* @param $note_id
335-
* @return mixed
336-
*/
424+
#[OA\Get(
425+
path: "/api/v1/summits/{id}/attendees/{attendee_id}/notes/{note_id}",
426+
summary: "Get a specific attendee note",
427+
operationId: 'getAttendeeNote',
428+
security: [['summit_attendee_notes_oauth2' => [
429+
SummitScopes::ReadAllSummitData,
430+
SummitScopes::ReadAttendeeNotesData,
431+
]]],
432+
tags: ["Attendee Notes"],
433+
parameters: [
434+
new OA\Parameter(name: "id", description: "Summit ID", in: "path", required: true, schema: new OA\Schema(type: "string")),
435+
new OA\Parameter(name: "attendee_id", description: "Attendee ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
436+
new OA\Parameter(name: "note_id", description: "Note ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
437+
new OA\Parameter(name: "expand", description: "Expand relations (author, owner, ticket)", in: "query", required: false, schema: new OA\Schema(type: "string")),
438+
],
439+
responses: [
440+
new OA\Response(
441+
response: Response::HTTP_OK,
442+
description: "OK",
443+
content: new OA\JsonContent(ref: "#/components/schemas/SummitAttendeeNote")
444+
),
445+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
446+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
447+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
448+
]
449+
)]
337450
public function getAttendeeNote($summit_id, $attendee_id, $note_id)
338451
{
339452
return $this->processRequest(function () use ($summit_id, $attendee_id, $note_id) {
@@ -363,11 +476,42 @@ public function getAttendeeNote($summit_id, $attendee_id, $note_id)
363476
});
364477
}
365478

366-
/**
367-
* @param $summit_id
368-
* @param $attendee_id
369-
* @return mixed
370-
*/
479+
#[OA\Post(
480+
path: "/api/v1/summits/{id}/attendees/{attendee_id}/notes",
481+
summary: "Add a note to an attendee",
482+
operationId: 'addAttendeeNote',
483+
security: [['summit_attendee_notes_oauth2' => [
484+
SummitScopes::WriteSummitData,
485+
SummitScopes::WriteAttendeeNotesData,
486+
]]],
487+
tags: ["Attendee Notes"],
488+
x: [
489+
'required-groups' => [
490+
IGroup::SuperAdmins,
491+
IGroup::Administrators,
492+
IGroup::SummitAdministrators,
493+
IGroup::SummitRegistrationAdmins,
494+
]
495+
],
496+
parameters: [
497+
new OA\Parameter(name: "id", description: "Summit ID", in: "path", required: true, schema: new OA\Schema(type: "string")),
498+
new OA\Parameter(name: "attendee_id", description: "Attendee ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
499+
],
500+
requestBody: new OA\RequestBody(
501+
required: true,
502+
content: new OA\JsonContent(ref: "#/components/schemas/AttendeeNoteAddRequest")
503+
),
504+
responses: [
505+
new OA\Response(
506+
response: Response::HTTP_CREATED,
507+
description: "Created",
508+
content: new OA\JsonContent(ref: "#/components/schemas/SummitAttendeeNote")
509+
),
510+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
511+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
512+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
513+
]
514+
)]
371515
public function addAttendeeNote($summit_id, $attendee_id)
372516
{
373517
return $this->processRequest(function () use ($summit_id, $attendee_id) {
@@ -389,12 +533,44 @@ public function addAttendeeNote($summit_id, $attendee_id)
389533
});
390534
}
391535

392-
/**
393-
* @param $summit_id
394-
* @param $attendee_id
395-
* @param $note_id
396-
* @return mixed
397-
*/
536+
#[OA\Put(
537+
path: "/api/v1/summits/{id}/attendees/{attendee_id}/notes/{note_id}",
538+
summary: "Update an attendee note",
539+
operationId: 'updateAttendeeNote',
540+
security: [['summit_attendee_notes_oauth2' => [
541+
SummitScopes::WriteSummitData,
542+
SummitScopes::WriteAttendeeNotesData,
543+
]]],
544+
tags: ["Attendee Notes"],
545+
x: [
546+
'required-groups' => [
547+
IGroup::SuperAdmins,
548+
IGroup::Administrators,
549+
IGroup::SummitAdministrators,
550+
IGroup::SummitRegistrationAdmins,
551+
]
552+
],
553+
parameters: [
554+
new OA\Parameter(name: "id", description: "Summit ID", in: "path", required: true, schema: new OA\Schema(type: "string")),
555+
new OA\Parameter(name: "attendee_id", description: "Attendee ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
556+
new OA\Parameter(name: "note_id", description: "Note ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
557+
],
558+
requestBody: new OA\RequestBody(
559+
required: true,
560+
content: new OA\JsonContent(ref: "#/components/schemas/AttendeeNoteUpdateRequest")
561+
),
562+
responses: [
563+
new OA\Response(
564+
response: Response::HTTP_OK,
565+
description: "OK - Note updated successfully",
566+
content: new OA\JsonContent(ref: "#/components/schemas/SummitAttendeeNote")
567+
),
568+
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
569+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
570+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
571+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
572+
]
573+
)]
398574
public function updateAttendeeNote($summit_id, $attendee_id, $note_id)
399575
{
400576
return $this->processRequest(function () use ($summit_id, $attendee_id, $note_id) {
@@ -416,12 +592,35 @@ public function updateAttendeeNote($summit_id, $attendee_id, $note_id)
416592
});
417593
}
418594

419-
/**
420-
* @param $summit_id
421-
* @param $attendee_id
422-
* @param $note_id
423-
* @return mixed
424-
*/
595+
#[OA\Delete(
596+
path: "/api/v1/summits/{id}/attendees/{attendee_id}/notes/{note_id}",
597+
summary: "Delete an attendee note",
598+
operationId: 'deleteAttendeeNote',
599+
security: [['summit_attendee_notes_oauth2' => [
600+
SummitScopes::WriteSummitData,
601+
SummitScopes::WriteAttendeeNotesData,
602+
]]],
603+
tags: ["Attendee Notes"],
604+
x: [
605+
'required-groups' => [
606+
IGroup::SuperAdmins,
607+
IGroup::Administrators,
608+
IGroup::SummitAdministrators,
609+
IGroup::SummitRegistrationAdmins,
610+
]
611+
],
612+
parameters: [
613+
new OA\Parameter(name: "id", description: "Summit ID", in: "path", required: true, schema: new OA\Schema(type: "string")),
614+
new OA\Parameter(name: "attendee_id", description: "Attendee ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
615+
new OA\Parameter(name: "note_id", description: "Note ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
616+
],
617+
responses: [
618+
new OA\Response(response: Response::HTTP_NO_CONTENT, description: "No Content - Note deleted successfully"),
619+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
620+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
621+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
622+
]
623+
)]
425624
public function deleteAttendeeNote($summit_id, $attendee_id, $note_id)
426625
{
427626
return $this->processRequest(function () use ($summit_id, $attendee_id, $note_id) {
@@ -433,4 +632,4 @@ public function deleteAttendeeNote($summit_id, $attendee_id, $note_id)
433632
return $this->deleted();
434633
});
435634
}
436-
}
635+
}

‎app/Swagger/Models/SummitAttendeeNoteSchema.php‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'SummitAttendeeNote',
9+
type: 'object',
10+
description: 'Note attached to an attendee (admin view with email)',
11+
required: ['id', 'created', 'last_edited', 'content'],
12+
properties: [
13+
new OA\Property(property: 'id', type: 'integer'),
14+
new OA\Property(property: 'created', type: 'integer', description: 'Unix timestamp'),
15+
new OA\Property(property: 'last_edited', type: 'integer', description: 'Unix timestamp'),
16+
new OA\Property(property: 'content', type: 'string', description: 'Note content'),
17+
new OA\Property(property: 'author_id', type: 'integer', example: 123, description: 'AdminMember ID. Replaced by AdminMember object when using ?expand=author'),
18+
new OA\Property(property: 'owner_id', type: 'integer', example: 456, description: 'SummitAttendee ID. Replaced by SummitAttendee object when using ?expand=owner'),
19+
new OA\Property(property: 'ticket_id', type: 'integer', example: 789, nullable: true, description: 'SummitAttendeeTicket ID. Replaced by SummitAttendeeTicket object when using ?expand=ticket'),
20+
]
21+
)]
22+
class SummitAttendeeNoteSchema {}

0 commit comments

Comments
 (0)