Skip to content

Commit ad60772

Browse files
matiasperrone-exomatiasperrone
matiasperrone-exo
and
matiasperrone
authored
Feature | Extend Swagger Coverage for controller OAuth2SummitPresentationActionApiController (#391)
* feat: Extend Swagger Coverage for controller OAuth2SummitPresentationActionApiController.php * fix: HTTP codes now uses Response::HTTP_* constants * fix: Move schema to the new file and remove requiere * fix: Change "namespace" word positioning * chore: Add the security schema for the controller to its own file * chore: include PR requested changes --------- Co-authored-by: Matias Perrone <github@matiasperrone.com>
1 parent 77132c5 commit ad60772

File tree

4 files changed

+223
-14
lines changed

4 files changed

+223
-14
lines changed

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

Lines changed: 169 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
<?php namespace App\Http\Controllers;
1+
<?php
2+
3+
namespace App\Http\Controllers;
4+
25
/**
36
* Copyright 2021 OpenStack Foundation
47
* Licensed under the Apache License, Version 2.0 (the "License");
@@ -11,21 +14,26 @@
1114
* See the License for the specific language governing permissions and
1215
* limitations under the License.
1316
**/
17+
use App\Models\Foundation\Main\IGroup;
18+
use App\Security\SummitScopes;
1419
use App\Services\Model\ISummitPresentationActionService;
20+
use Illuminate\Http\Response;
1521
use Illuminate\Support\Facades\Log;
1622
use Illuminate\Support\Facades\Request;
1723
use models\exceptions\EntityNotFoundException;
1824
use models\exceptions\ValidationException;
1925
use models\oauth2\IResourceServerContext;
2026
use models\summit\ISummitRepository;
2127
use ModelSerializers\SerializerRegistry;
28+
use OpenApi\Attributes as OA;
2229
use Exception;
30+
31+
2332
/**
2433
* Class OAuth2SummitPresentationActionApiController
2534
* @package App\Http\Controllers
2635
*/
27-
final class OAuth2SummitPresentationActionApiController
28-
extends OAuth2ProtectedController
36+
final class OAuth2SummitPresentationActionApiController extends OAuth2ProtectedController
2937
{
3038

3139
/**
@@ -49,24 +57,100 @@ public function __construct
4957
ISummitRepository $summit_repository,
5058
ISummitPresentationActionService $service,
5159
IResourceServerContext $resource_server_context
52-
)
53-
{
60+
) {
5461
$this->summit_repository = $summit_repository;
5562
$this->service = $service;
5663
parent::__construct($resource_server_context);
5764
}
5865

66+
// OpenAPI Documentation
67+
68+
#[OA\Put(
69+
path: '/api/v1/summits/{id}/selection-plans/{selection_plan_id}/presentations/{presentation_id}/actions/{action_type_id}/complete',
70+
operationId: 'completePresentationAction',
71+
summary: 'Mark a presentation action as completed',
72+
description: 'Marks a specific action for a presentation as completed by a track chair. Track chairs use presentation actions to manage the review process (e.g., "Review Video", "Check Speakers", "Verify Content"). Only track chairs and track chair admins can perform this action.',
73+
x: [
74+
'required-groups' => [
75+
IGroup::SuperAdmins,
76+
IGroup::Administrators,
77+
IGroup::TrackChairs,
78+
IGroup::TrackChairsAdmins,
79+
]
80+
],
81+
security: [
82+
[
83+
'presentation_actions_oauth2' => [
84+
SummitScopes::WriteSummitData,
85+
SummitScopes::WriteEventData,
86+
]
87+
]
88+
],
89+
tags: ['Presentation Actions'],
90+
parameters: [
91+
new OA\Parameter(
92+
name: 'id',
93+
in: 'path',
94+
required: true,
95+
description: 'Summit ID',
96+
schema: new OA\Schema(type: 'integer')
97+
),
98+
new OA\Parameter(
99+
name: 'selection_plan_id',
100+
in: 'path',
101+
required: true,
102+
description: 'Selection Plan ID',
103+
schema: new OA\Schema(type: 'integer')
104+
),
105+
new OA\Parameter(
106+
name: 'presentation_id',
107+
in: 'path',
108+
required: true,
109+
description: 'Presentation ID',
110+
schema: new OA\Schema(type: 'integer')
111+
),
112+
new OA\Parameter(
113+
name: 'action_type_id',
114+
in: 'path',
115+
required: true,
116+
description: 'Action Type ID',
117+
schema: new OA\Schema(type: 'integer')
118+
),
119+
new OA\Parameter(
120+
name: 'expand',
121+
in: 'query',
122+
required: false,
123+
description: 'Expand relationships. Available: presentation, type, created_by, updated_by',
124+
schema: new OA\Schema(type: 'string', example: 'type,created_by')
125+
),
126+
],
127+
responses: [
128+
new OA\Response(
129+
response: 200,
130+
description: 'Presentation action marked as completed successfully',
131+
content: new OA\JsonContent(ref: '#/components/schemas/PresentationAction')
132+
),
133+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
134+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden - User must be a track chair or track chair admin"),
135+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
136+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
137+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
138+
]
139+
)]
140+
59141
/**
60142
* @param $summit_id
61143
* @param $selection_plan_id
62144
* @param $presentation_id
63145
* @param $action_type_id
64146
*/
65-
public function complete($summit_id, $selection_plan_id, $presentation_id, $action_type_id){
147+
public function complete($summit_id, $selection_plan_id, $presentation_id, $action_type_id)
148+
{
66149
try {
67150

68151
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->resource_server_context)->find($summit_id);
69-
if (is_null($summit)) return $this->error404();
152+
if (is_null($summit))
153+
return $this->error404();
70154

71155
$member = $this->resource_server_context->getCurrentUser();
72156

@@ -78,7 +162,7 @@ public function complete($summit_id, $selection_plan_id, $presentation_id, $acti
78162
if (!$authz)
79163
return $this->error403();
80164

81-
$action = $this->service->updateAction($summit, intval($selection_plan_id), intval($presentation_id), intval($action_type_id), true );
165+
$action = $this->service->updateAction($summit, intval($selection_plan_id), intval($presentation_id), intval($action_type_id), true);
82166
return $this->updated(SerializerRegistry::getInstance()->getSerializer($action)->serialize(Request::input('expand', '')));
83167

84168
} catch (ValidationException $ex) {
@@ -93,17 +177,91 @@ public function complete($summit_id, $selection_plan_id, $presentation_id, $acti
93177
}
94178
}
95179

180+
#[OA\Delete(
181+
path: '/api/v1/summits/{id}/selection-plans/{selection_plan_id}/presentations/{presentation_id}/actions/{action_type_id}/incomplete',
182+
operationId: 'incompletePresentationAction',
183+
summary: 'Mark a presentation action as incomplete',
184+
description: 'Unmarks a completed presentation action, setting it back to incomplete status. This allows track chairs to revert an action they previously marked as done. Only track chairs and track chair admins can perform this action.',
185+
x: [
186+
'required-groups' => [
187+
IGroup::SuperAdmins,
188+
IGroup::Administrators,
189+
IGroup::TrackChairs,
190+
IGroup::TrackChairsAdmins,
191+
]
192+
],
193+
security: [
194+
[
195+
'presentation_actions_oauth2' => [
196+
SummitScopes::WriteSummitData,
197+
]
198+
]
199+
],
200+
tags: ['Presentation Actions'],
201+
parameters: [
202+
new OA\Parameter(
203+
name: 'id',
204+
in: 'path',
205+
required: true,
206+
description: 'Summit ID',
207+
schema: new OA\Schema(type: 'integer')
208+
),
209+
new OA\Parameter(
210+
name: 'selection_plan_id',
211+
in: 'path',
212+
required: true,
213+
description: 'Selection Plan ID',
214+
schema: new OA\Schema(type: 'integer')
215+
),
216+
new OA\Parameter(
217+
name: 'presentation_id',
218+
in: 'path',
219+
required: true,
220+
description: 'Presentation ID',
221+
schema: new OA\Schema(type: 'integer')
222+
),
223+
new OA\Parameter(
224+
name: 'action_type_id',
225+
in: 'path',
226+
required: true,
227+
description: 'Action Type ID',
228+
schema: new OA\Schema(type: 'integer')
229+
),
230+
new OA\Parameter(
231+
name: 'expand',
232+
in: 'query',
233+
required: false,
234+
description: 'Expand relationships. Available: presentation, type, created_by, updated_by',
235+
schema: new OA\Schema(type: 'string', example: 'type,created_by')
236+
),
237+
],
238+
responses: [
239+
new OA\Response(
240+
response: 200,
241+
description: 'Presentation action marked as incomplete successfully',
242+
content: new OA\JsonContent(ref: '#/components/schemas/PresentationAction')
243+
),
244+
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
245+
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden - User must be a track chair or track chair admin"),
246+
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"),
247+
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
248+
new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error"),
249+
]
250+
)]
251+
96252
/**
97253
* @param $summit_id
98254
* @param $selection_plan_id
99255
* @param $presentation_id
100256
* @param $action_type_id
101257
*/
102-
public function uncomplete($summit_id, $selection_plan_id, $presentation_id, $action_type_id){
258+
public function uncomplete($summit_id, $selection_plan_id, $presentation_id, $action_type_id)
259+
{
103260
try {
104261

105262
$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->resource_server_context)->find($summit_id);
106-
if (is_null($summit)) return $this->error404();
263+
if (is_null($summit))
264+
return $this->error404();
107265

108266
$member = $this->resource_server_context->getCurrentUser();
109267

@@ -115,7 +273,7 @@ public function uncomplete($summit_id, $selection_plan_id, $presentation_id, $ac
115273
if (!$authz)
116274
return $this->error403();
117275

118-
$action = $this->service->updateAction($summit, intval($selection_plan_id), intval($presentation_id), intval($action_type_id), false );
276+
$action = $this->service->updateAction($summit, intval($selection_plan_id), intval($presentation_id), intval($action_type_id), false);
119277

120278
return $this->updated(SerializerRegistry::getInstance()->getSerializer($action)->serialize(Request::input('expand', '')));
121279
} catch (ValidationException $ex) {

‎app/Swagger/Models/PresentationActionSchema.php‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
// Presentation Actions
8+
9+
#[OA\Schema(
10+
schema: 'PresentationAction',
11+
type: 'object',
12+
properties: [
13+
new OA\Property(property: 'id', type: 'integer', example: 1),
14+
new OA\Property(property: 'created', type: 'integer', example: 1633024800, description: 'Unix timestamp when created'),
15+
new OA\Property(property: 'last_edited', type: 'integer', example: 1633111200, description: 'Unix timestamp when last updated'),
16+
new OA\Property(property: 'is_completed', type: 'boolean', example: true, description: 'Whether the action has been completed'),
17+
new OA\Property(property: 'presentation_id', type: 'integer', example: 10, description: 'Presentation ID, use expand=presentation for full object details'),
18+
new OA\Property(property: 'type_id', type: 'integer', example: 5, description: 'SummitEventType ID, use expand=type for full object details'),
19+
new OA\Property(property: 'created_by_id', type: 'integer', nullable: true, example: 42, description: 'Member ID of the user who created this action, use expand=created_by for full object details'),
20+
new OA\Property(property: 'updated_by_id', type: 'integer', nullable: true, example: 42, description: 'Member ID of the user who last updated this action, use expand=updated_by for full object details'),
21+
new OA\Property(property: 'created_by', ref: '#/components/schemas/Member'),
22+
new OA\Property(property: 'updated_by', ref: '#/components/schemas/Member'),
23+
],
24+
)]
25+
class PresentationActionSchema
26+
{
27+
}

‎app/Swagger/Security/PresentationActionsAuthSchema.php‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use App\Security\SummitScopes;
6+
use OpenApi\Attributes as OA;
7+
8+
#[OA\SecurityScheme(
9+
type: 'oauth2',
10+
securityScheme: 'presentation_actions_oauth2',
11+
flows: [
12+
new OA\Flow(
13+
authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
14+
tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
15+
flow: 'authorizationCode',
16+
scopes: [
17+
SummitScopes::WriteSummitData => 'Write Summit Data',
18+
SummitScopes::WriteEventData => 'Write Event Data',
19+
],
20+
),
21+
],
22+
)
23+
]
24+
class PresentationActionsAuthSchema
25+
{
26+
}

‎app/Swagger/SummitPresentationSchemas.php‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,4 @@
22

33
namespace App\Swagger\schemas;
44

5-
use OpenApi\Attributes as OA;
6-
7-
//
5+
use OpenApi\Attributes as OA;

0 commit comments

Comments
 (0)