Skip to content

Feature | Extend Swagger Coverage for controller OAuth2SummitPresentationActionApiController #391

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
smarcet merged 6 commits into from
Dec 3, 2025
Merged

Feature | Extend Swagger Coverage for controller OAuth2SummitPresentationActionApiController #391

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7a6b584
feat: Extend Swagger Coverage for controller OAuth2SummitPresentation…
matiasperrone-exo Oct 2, 2025
89dd97c
fix: HTTP codes now uses Response::HTTP_* constants
matiasperrone-exo Oct 2, 2025
aa008ca
fix: Move schema to the new file and remove requiere
matiasperrone-exo Oct 9, 2025
51bc32c
fix: Change "namespace" word positioning
matiasperrone-exo Oct 14, 2025
fc71a25
chore: Add the security schema for the controller to its own file
matiasperrone Nov 13, 2025
b07a9f6
chore: include PR requested changes
matiasperrone Nov 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 169 additions & 11 deletions app/Http/Controllers/Apis/Protected/Summit/OAuth2SummitPresentationActionApiController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
<?php namespace App\Http\Controllers;
<?php

namespace App\Http\Controllers;

/**
* Copyright 2021 OpenStack Foundation
* Licensed under the Apache License, Version 2.0 (the "License");
Expand All @@ -11,21 +14,26 @@
* See the License for the specific language governing permissions and
* limitations under the License.
**/
use App\Models\Foundation\Main\IGroup;
use App\Security\SummitScopes;
use App\Services\Model\ISummitPresentationActionService;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Request;
use models\exceptions\EntityNotFoundException;
use models\exceptions\ValidationException;
use models\oauth2\IResourceServerContext;
use models\summit\ISummitRepository;
use ModelSerializers\SerializerRegistry;
use OpenApi\Attributes as OA;
use Exception;


/**
* Class OAuth2SummitPresentationActionApiController
* @package App\Http\Controllers
*/
final class OAuth2SummitPresentationActionApiController
extends OAuth2ProtectedController
final class OAuth2SummitPresentationActionApiController extends OAuth2ProtectedController
{

/**
Expand All @@ -49,24 +57,100 @@ public function __construct
ISummitRepository $summit_repository,
ISummitPresentationActionService $service,
IResourceServerContext $resource_server_context
)
{
) {
$this->summit_repository = $summit_repository;
$this->service = $service;
parent::__construct($resource_server_context);
}

// OpenAPI Documentation

#[OA\Put(
path: '/api/v1/summits/{id}/selection-plans/{selection_plan_id}/presentations/{presentation_id}/actions/{action_type_id}/complete',
operationId: 'completePresentationAction',
summary: 'Mark a presentation action as completed',
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.',
x: [
'required-groups' => [
IGroup::SuperAdmins,
IGroup::Administrators,
IGroup::TrackChairs,
IGroup::TrackChairsAdmins,
]
],
security: [
[
'presentation_actions_oauth2' => [
SummitScopes::WriteSummitData,
SummitScopes::WriteEventData,
]
]
],
tags: ['Presentation Actions'],
parameters: [
new OA\Parameter(
name: 'id',
in: 'path',
required: true,
description: 'Summit ID',
schema: new OA\Schema(type: 'integer')
),
new OA\Parameter(
name: 'selection_plan_id',
in: 'path',
required: true,
description: 'Selection Plan ID',
schema: new OA\Schema(type: 'integer')
),
new OA\Parameter(
name: 'presentation_id',
in: 'path',
required: true,
description: 'Presentation ID',
schema: new OA\Schema(type: 'integer')
),
new OA\Parameter(
name: 'action_type_id',
in: 'path',
required: true,
description: 'Action Type ID',
schema: new OA\Schema(type: 'integer')
),
new OA\Parameter(
name: 'expand',
in: 'query',
required: false,
description: 'Expand relationships. Available: presentation, type, created_by, updated_by',
schema: new OA\Schema(type: 'string', example: 'type,created_by')
),
],
responses: [
new OA\Response(
response: 200,
description: 'Presentation action marked as completed successfully',
content: new OA\JsonContent(ref: '#/components/schemas/PresentationAction')
),
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden - User must be a track chair or track chair admin"),
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"),
]
)]

/**
* @param $summit_id
* @param $selection_plan_id
* @param $presentation_id
* @param $action_type_id
*/
public function complete($summit_id, $selection_plan_id, $presentation_id, $action_type_id){
public function complete($summit_id, $selection_plan_id, $presentation_id, $action_type_id)
{
try {

$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->resource_server_context)->find($summit_id);
if (is_null($summit)) return $this->error404();
if (is_null($summit))
return $this->error404();

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

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

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

} catch (ValidationException $ex) {
Expand All @@ -93,17 +177,91 @@ public function complete($summit_id, $selection_plan_id, $presentation_id, $acti
}
}

#[OA\Delete(
path: '/api/v1/summits/{id}/selection-plans/{selection_plan_id}/presentations/{presentation_id}/actions/{action_type_id}/incomplete',
operationId: 'incompletePresentationAction',
summary: 'Mark a presentation action as incomplete',
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.',
x: [
'required-groups' => [
IGroup::SuperAdmins,
IGroup::Administrators,
IGroup::TrackChairs,
IGroup::TrackChairsAdmins,
]
],
security: [
[
'presentation_actions_oauth2' => [
SummitScopes::WriteSummitData,
]
]
],
tags: ['Presentation Actions'],
parameters: [
new OA\Parameter(
name: 'id',
in: 'path',
required: true,
description: 'Summit ID',
schema: new OA\Schema(type: 'integer')
),
new OA\Parameter(
name: 'selection_plan_id',
in: 'path',
required: true,
description: 'Selection Plan ID',
schema: new OA\Schema(type: 'integer')
),
new OA\Parameter(
name: 'presentation_id',
in: 'path',
required: true,
description: 'Presentation ID',
schema: new OA\Schema(type: 'integer')
),
new OA\Parameter(
name: 'action_type_id',
in: 'path',
required: true,
description: 'Action Type ID',
schema: new OA\Schema(type: 'integer')
),
new OA\Parameter(
name: 'expand',
in: 'query',
required: false,
description: 'Expand relationships. Available: presentation, type, created_by, updated_by',
schema: new OA\Schema(type: 'string', example: 'type,created_by')
),
],
responses: [
new OA\Response(
response: 200,
description: 'Presentation action marked as incomplete successfully',
content: new OA\JsonContent(ref: '#/components/schemas/PresentationAction')
),
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden - User must be a track chair or track chair admin"),
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"),
]
)]

/**
* @param $summit_id
* @param $selection_plan_id
* @param $presentation_id
* @param $action_type_id
*/
public function uncomplete($summit_id, $selection_plan_id, $presentation_id, $action_type_id){
public function uncomplete($summit_id, $selection_plan_id, $presentation_id, $action_type_id)
{
try {

$summit = SummitFinderStrategyFactory::build($this->summit_repository, $this->resource_server_context)->find($summit_id);
if (is_null($summit)) return $this->error404();
if (is_null($summit))
return $this->error404();

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

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

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

return $this->updated(SerializerRegistry::getInstance()->getSerializer($action)->serialize(Request::input('expand', '')));
} catch (ValidationException $ex) {
Expand Down
27 changes: 27 additions & 0 deletions app/Swagger/Models/PresentationActionSchema.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<?php

namespace App\Swagger\schemas;

use OpenApi\Attributes as OA;

// Presentation Actions

#[OA\Schema(
schema: 'PresentationAction',
type: 'object',
properties: [
new OA\Property(property: 'id', type: 'integer', example: 1),
new OA\Property(property: 'created', type: 'integer', example: 1633024800, description: 'Unix timestamp when created'),
new OA\Property(property: 'last_edited', type: 'integer', example: 1633111200, description: 'Unix timestamp when last updated'),
new OA\Property(property: 'is_completed', type: 'boolean', example: true, description: 'Whether the action has been completed'),
new OA\Property(property: 'presentation_id', type: 'integer', example: 10, description: 'Presentation ID, use expand=presentation for full object details'),
new OA\Property(property: 'type_id', type: 'integer', example: 5, description: 'SummitEventType ID, use expand=type for full object details'),
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'),
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'),
new OA\Property(property: 'created_by', ref: '#/components/schemas/Member'),
new OA\Property(property: 'updated_by', ref: '#/components/schemas/Member'),
],
)]
class PresentationActionSchema
{
}
26 changes: 26 additions & 0 deletions app/Swagger/Security/PresentationActionsAuthSchema.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<?php

namespace App\Swagger\schemas;

use App\Security\SummitScopes;
use OpenApi\Attributes as OA;

#[OA\SecurityScheme(
type: 'oauth2',
securityScheme: 'presentation_actions_oauth2',
flows: [
new OA\Flow(
authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
flow: 'authorizationCode',
scopes: [
SummitScopes::WriteSummitData => 'Write Summit Data',
SummitScopes::WriteEventData => 'Write Event Data',
],
),
],
)
]
class PresentationActionsAuthSchema
{
}
4 changes: 1 addition & 3 deletions app/Swagger/SummitPresentationSchemas.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,4 @@

namespace App\Swagger\schemas;

use OpenApi\Attributes as OA;

//
use OpenApi\Attributes as OA;