Skip to content

Commit 5b75fdc

Browse files
matiasperrone-exomatiasperrone
matiasperrone-exo
and
matiasperrone
authored
Feature | Extend Swagger Coverage for controller OAuth2SummitSelectionPlansApiController (#480)
* feat: initial version of the OpenAPI documentation of the controller Signed-off-by: Matias Perrone <github@matiasperrone.com> * chore: unify tags name Signed-off-by: Matias Perrone <github@matiasperrone.com> * chore: reorder OpenAPI attributes * chore: add missing model serializer attributes Signed-off-by: Matias Perrone <github@matiasperrone.com> * chore: Add missing schemas and documentation * chore: add missing params and request bodies * chore: fix build Signed-off-by: Matias Perrone <github@matiasperrone.com> * chore: remove repeated schema Signed-off-by: Matias Perrone <github@matiasperrone.com> * chore: Fix inconsistencies with HTTP code responses and create the correct response schema Signed-off-by: Matias Perrone <github@matiasperrone.com> --------- Signed-off-by: Matias Perrone <github@matiasperrone.com> Co-authored-by: Matias Perrone <github@matiasperrone.com>
1 parent 5fed732 commit 5b75fdc

22 files changed

Lines changed: 4170 additions & 33 deletions

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

Lines changed: 2897 additions & 1 deletion
Large diffs are not rendered by default.

‎app/Swagger/Models/AdminPresentationSchema.php‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'AdminPresentation',
9+
type: 'object',
10+
description: 'Represents a presentation with admin-specific fields including statistics and selection data',
11+
allOf: [
12+
new OA\Schema(ref: '#/components/schemas/Presentation'),
13+
new OA\Schema(
14+
type: 'object',
15+
properties: [
16+
// AdminPresentation-specific fields
17+
new OA\Property(property: 'rank', type: 'integer', nullable: true, example: 5, description: 'Presentation rank in selection'),
18+
new OA\Property(property: 'selection_status', type: 'string', nullable: true, example: 'selected', description: 'Selection status (selected, unselected, lightning-accepted, etc.)'),
19+
new OA\Property(property: 'views_count', type: 'integer', example: 150, description: 'Number of views by track chairs'),
20+
new OA\Property(property: 'comments_count', type: 'integer', example: 8, description: 'Number of comments'),
21+
new OA\Property(property: 'popularity_score', type: 'number', format: 'float', example: 4.5, description: 'Calculated popularity score'),
22+
new OA\Property(property: 'votes_count', type: 'integer', example: 42, description: 'Number of attendee votes'),
23+
new OA\Property(property: 'votes_average', type: 'number', format: 'float', example: 3.8, description: 'Average vote rating'),
24+
new OA\Property(property: 'votes_total_points', type: 'integer', example: 160, description: 'Total vote points'),
25+
new OA\Property(property: 'track_chair_avg_score', type: 'number', format: 'float', example: 4.2, description: 'Average track chair score'),
26+
new OA\Property(property: 'remaining_selections', type: 'integer', example: 3, description: 'Remaining selections available'),
27+
new OA\Property(property: 'passers_count', type: 'integer', example: 2, description: 'Number of track chairs who passed'),
28+
new OA\Property(property: 'likers_count', type: 'integer', example: 5, description: 'Number of track chairs who marked as maybe'),
29+
new OA\Property(property: 'selectors_count', type: 'integer', example: 8, description: 'Number of track chairs who selected'),
30+
new OA\Property(
31+
property: 'track_chair_scores_avg',
32+
type: 'array',
33+
description: 'Average scores per ranking type',
34+
items: new OA\Items(type: 'string'),
35+
example: ['Content: 4.5', 'Quality: 4.0']
36+
),
37+
38+
// Streaming/occupancy fields
39+
new OA\Property(property: 'occupancy', type: 'string', nullable: true, example: 'FULL', description: 'Room occupancy status'),
40+
new OA\Property(property: 'streaming_url', type: 'string', format: 'uri', nullable: true, example: 'https://stream.example.com/live/123'),
41+
new OA\Property(property: 'streaming_type', type: 'string', nullable: true, example: 'VOD', description: 'Type of streaming (VOD, LIVE, etc.)'),
42+
new OA\Property(property: 'etherpad_link', type: 'string', format: 'uri', nullable: true, example: 'https://etherpad.example.com/p/session123'),
43+
new OA\Property(property: 'overflow_streaming_url', type: 'string', format: 'uri', nullable: true, example: 'https://overflow.example.com/live/123'),
44+
new OA\Property(property: 'overflow_stream_is_secure', type: 'boolean', example: false),
45+
new OA\Property(property: 'overflow_stream_key', type: 'string', nullable: true, example: 'abc123key'),
46+
]
47+
),
48+
],
49+
)]
50+
class AdminPresentationSchema {}

‎app/Swagger/Models/AssignedSelectionPlanExtraQuestionTypeSchema.php‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'AssignedSelectionPlanExtraQuestionType',
9+
type: 'object',
10+
description: 'Represents an extra question type assigned to a selection plan with order and editability settings',
11+
properties: [
12+
new OA\Property(property: 'id', type: 'integer', example: 1),
13+
new OA\Property(property: 'created', type: 'integer', description: 'Unix timestamp', example: 1640995200),
14+
new OA\Property(property: 'last_edited', type: 'integer', description: 'Unix timestamp', example: 1640995200),
15+
new OA\Property(property: 'order', type: 'integer', example: 1, description: 'Order of the question within the selection plan'),
16+
new OA\Property(property: 'is_editable', type: 'boolean', example: true, description: 'Whether the question can be edited'),
17+
new OA\Property(property: 'selection_plan_id', type: 'integer', example: 123, description: 'Selection Plan ID'),
18+
new OA\Property(property: 'name', type: 'string', example: 'audience_level'),
19+
new OA\Property(property: 'type', type: 'string', example: 'ComboBox'),
20+
new OA\Property(property: 'label', type: 'string', example: 'What is your target audience level?'),
21+
new OA\Property(property: 'placeholder', type: 'string', nullable: true, example: 'Select an option'),
22+
new OA\Property(property: 'mandatory', type: 'boolean', example: true),
23+
new OA\Property(property: 'max_selected_values', type: 'integer', example: 0),
24+
new OA\Property(property: 'class', type: 'string', example: 'SummitSelectionPlanExtraQuestionType'),
25+
new OA\Property(property: 'summit_id', type: 'integer', example: 123),
26+
new OA\Property(
27+
property: 'values',
28+
type: 'array',
29+
description: 'Array of ExtraQuestionTypeValue IDs',
30+
items: new OA\Items(type: 'integer'),
31+
example: [1, 2, 3]
32+
),
33+
]
34+
)]
35+
class AssignedSelectionPlanExtraQuestionTypeSchema {}

‎app/Swagger/Models/ExtraQuestionAnswerSchema.php‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'ExtraQuestionAnswer',
9+
type: 'object',
10+
description: 'Represents an answer to an extra question',
11+
properties: [
12+
// Base fields (from SilverStripeSerializer)
13+
new OA\Property(property: 'id', type: 'integer', example: 1),
14+
new OA\Property(property: 'created', type: 'integer', description: 'Unix timestamp', example: 1640995200),
15+
new OA\Property(property: 'last_edited', type: 'integer', description: 'Unix timestamp', example: 1640995200),
16+
17+
// ExtraQuestionAnswer fields
18+
new OA\Property(property: 'value', type: 'string', example: 'Yes, I agree', description: 'The answer value'),
19+
new OA\Property(property: 'question_id', type: 'integer', example: 5, description: 'ExtraQuestionType ID'),
20+
21+
// Expandable relations
22+
new OA\Property(property: 'question', type: 'object', description: 'ExtraQuestionType object, expanded when using expand=question'),
23+
]
24+
)]
25+
class ExtraQuestionAnswerSchema {}

‎app/Swagger/Models/PresentationActionTypeSchema.php‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'PresentationActionType',
9+
type: 'object',
10+
description: 'Represents an action type that can be performed on presentations (e.g., "Flag for Review", "Mark as Complete")',
11+
properties: [
12+
new OA\Property(property: 'id', type: 'integer', example: 1),
13+
new OA\Property(property: 'created', type: 'integer', description: 'Unix timestamp', example: 1640995200),
14+
new OA\Property(property: 'last_edited', type: 'integer', description: 'Unix timestamp', example: 1640995200),
15+
new OA\Property(property: 'label', type: 'string', example: 'Flag for Review'),
16+
new OA\Property(property: 'summit_id', type: 'integer', example: 123, description: 'Summit ID'),
17+
new OA\Property(property: 'order', type: 'integer', example: 1, description: 'Order within the selection plan (when queried in context)'),
18+
]
19+
)]
20+
class PresentationActionTypeSchema {}

‎app/Swagger/Models/PresentationLinkSchema.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 OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'PresentationLink',
9+
type: 'object',
10+
description: 'Represents an external link associated with a presentation',
11+
properties: [
12+
// Base fields (from SilverStripeSerializer)
13+
new OA\Property(property: 'id', type: 'integer', example: 1),
14+
new OA\Property(property: 'created', type: 'integer', description: 'Unix timestamp', example: 1640995200),
15+
new OA\Property(property: 'last_edited', type: 'integer', description: 'Unix timestamp', example: 1640995200),
16+
17+
// PresentationMaterial fields
18+
new OA\Property(property: 'name', type: 'string', example: 'Related Documentation'),
19+
new OA\Property(property: 'description', type: 'string', nullable: true, example: 'Link to the project documentation'),
20+
new OA\Property(property: 'display_on_site', type: 'boolean', example: true),
21+
new OA\Property(property: 'featured', type: 'boolean', example: false),
22+
new OA\Property(property: 'order', type: 'integer', example: 1),
23+
new OA\Property(property: 'presentation_id', type: 'integer', example: 123, description: 'Presentation ID'),
24+
new OA\Property(property: 'class_name', type: 'string', example: 'PresentationLink'),
25+
26+
// PresentationLink-specific fields
27+
new OA\Property(property: 'link', type: 'string', format: 'uri', nullable: true, example: 'https://docs.example.com/project', description: 'External URL'),
28+
]
29+
)]
30+
class PresentationLinkSchema {}

‎app/Swagger/Models/PresentationMediaUploadSchema.php‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'PresentationMediaUpload',
9+
type: 'object',
10+
description: 'Represents a media file uploaded for a presentation',
11+
properties: [
12+
// Base fields (from SilverStripeSerializer)
13+
new OA\Property(property: 'id', type: 'integer', example: 1),
14+
new OA\Property(property: 'created', type: 'integer', description: 'Unix timestamp', example: 1640995200),
15+
new OA\Property(property: 'last_edited', type: 'integer', description: 'Unix timestamp', example: 1640995200),
16+
17+
// PresentationMaterial fields (some are overridden)
18+
new OA\Property(property: 'name', type: 'string', nullable: true, example: 'Speaker Photo', description: 'Derived from media upload type name'),
19+
new OA\Property(property: 'description', type: 'string', nullable: true, example: 'Photo of the speaker', description: 'Derived from media upload type description'),
20+
new OA\Property(property: 'display_on_site', type: 'boolean', example: true),
21+
new OA\Property(property: 'order', type: 'integer', example: 1),
22+
new OA\Property(property: 'presentation_id', type: 'integer', example: 123, description: 'Presentation ID'),
23+
new OA\Property(property: 'class_name', type: 'string', example: 'PresentationMediaUpload'),
24+
25+
// PresentationMediaUpload-specific fields
26+
new OA\Property(property: 'filename', type: 'string', example: 'speaker-photo.jpg', description: 'Name of the uploaded file'),
27+
new OA\Property(property: 'media_upload_type_id', type: 'integer', example: 5, description: 'SummitMediaUploadType ID'),
28+
new OA\Property(property: 'public_url', type: 'string', format: 'uri', nullable: true, example: 'https://storage.example.com/uploads/speaker-photo.jpg', description: 'Public URL to access the uploaded file'),
29+
30+
// Expandable relations
31+
new OA\Property(property: 'media_upload_type', description: 'SummitMediaUploadType object, expanded when using expand=media_upload_type'),
32+
]
33+
)]
34+
class PresentationMediaUploadSchema {}

0 commit comments

Comments
 (0)