From 30e97c8e895dfda5b3c8cbd4533de8200653d411 Mon Sep 17 00:00:00 2001 From: Buster Neece Date: Sat, 8 Mar 2025 11:13:18 -0600 Subject: [PATCH] Add run-sync and file list endpoint docs. --- .../Controller/Api/Admin/Debug/SyncAction.php | 40 +++++++++-- .../Api/Stations/Files/ListAction.php | 45 +++++++++++- web/static/openapi.yml | 68 +++++++++++++++++++ 3 files changed, 144 insertions(+), 9 deletions(-) diff --git a/backend/src/Controller/Api/Admin/Debug/SyncAction.php b/backend/src/Controller/Api/Admin/Debug/SyncAction.php index 9df7c62aa1..d95f18aca6 100644 --- a/backend/src/Controller/Api/Admin/Debug/SyncAction.php +++ b/backend/src/Controller/Api/Admin/Debug/SyncAction.php @@ -7,17 +7,45 @@ use App\Console\Command\Sync\SingleTaskCommand; use App\Container\LoggerAwareTrait; use App\Controller\SingleActionInterface; +use App\Entity\Api\Admin\Debug\LogResult; use App\Event\GetSyncTasks; use App\Http\Response; use App\Http\ServerRequest; +use App\OpenApi; use Monolog\Handler\TestHandler; use Monolog\Level; +use OpenApi\Attributes as OA; use Psr\EventDispatcher\EventDispatcherInterface; use Psr\Http\Message\ResponseInterface; -/* - * TODO API - */ +#[ + OA\Put( + path: '/admin/debug/sync/{task}', + operationId: 'adminDebugRunSyncTask', + description: 'Manually run a scheduled synchronized task by name.', + tags: [OpenApi::TAG_ADMIN_DEBUG], + parameters: [ + new OA\Parameter( + name: 'task', + description: 'Synchronized task (either class name or "all").', + in: 'path', + required: true, + schema: new OA\Schema( + type: 'string' + ) + ), + ], + responses: [ + new OpenApi\Response\Success( + content: new OA\JsonContent( + ref: LogResult::class + ) + ), + new OpenApi\Response\AccessDenied(), + new OpenApi\Response\GenericError(), + ] + ), +] final class SyncAction implements SingleActionInterface { use LoggerAwareTrait; @@ -54,8 +82,8 @@ public function __invoke( $this->logger->popHandler(); } - return $response->withJson([ - 'logs' => $testHandler->getRecords(), - ]); + return $response->withJson( + LogResult::fromTestHandlerRecords($testHandler->getRecords()) + ); } } diff --git a/backend/src/Controller/Api/Stations/Files/ListAction.php b/backend/src/Controller/Api/Stations/Files/ListAction.php index a1b9b3d09e..1da88b20b7 100644 --- a/backend/src/Controller/Api/Stations/Files/ListAction.php +++ b/backend/src/Controller/Api/Stations/Files/ListAction.php @@ -19,19 +19,58 @@ use App\Http\RouterInterface; use App\Http\ServerRequest; use App\Media\MimeType; +use App\OpenApi; use App\Paginator; use App\Utilities\Strings; use App\Utilities\Types; use Doctrine\Common\Collections\Order; use Doctrine\ORM\QueryBuilder; use League\Flysystem\StorageAttributes; +use OpenApi\Attributes as OA; use Psr\Http\Message\ResponseInterface; use Psr\SimpleCache\CacheInterface; use Symfony\Component\PropertyAccess\PropertyAccessorInterface; -/* - * TODO API - */ +#[ + OA\Get( + path: '/station/{station_id}/files/list', + operationId: 'getStationFileList', + description: 'List files in the media directory by path.', + tags: [OpenApi::TAG_STATIONS_MEDIA], + parameters: [ + new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED), + new OA\Parameter( + name: 'currentDirectory', + in: 'query', + required: true, + schema: new OA\Schema(type: 'string') + ), + new OA\Parameter( + name: 'searchPhrase', + in: 'query', + schema: new OA\Schema(type: 'string', nullable: true) + ), + new OA\Parameter( + name: 'flushCache', + in: 'query', + schema: new OA\Schema(type: 'boolean', default: false, nullable: true), + ), + ], + responses: [ + new OpenApi\Response\Success( + content: new OA\JsonContent( + type: 'array', + items: new OA\Items( + ref: FileList::class + ) + ) + ), + new OpenApi\Response\AccessDenied(), + new OpenApi\Response\NotFound(), + new OpenApi\Response\GenericError(), + ] + ) +] final class ListAction implements SingleActionInterface { use CanSortResults; diff --git a/web/static/openapi.yml b/web/static/openapi.yml index 675f26bc9c..50ea14f7a9 100644 --- a/web/static/openapi.yml +++ b/web/static/openapi.yml @@ -488,6 +488,31 @@ paths: $ref: '#/components/responses/AccessDenied' '500': $ref: '#/components/responses/GenericError' + '/admin/debug/sync/{task}': + put: + tags: + - 'Administration: Debugging' + description: 'Manually run a scheduled synchronized task by name.' + operationId: adminDebugRunSyncTask + parameters: + - + name: task + in: path + description: 'Synchronized task (either class name or "all").' + required: true + schema: + type: string + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Api_Admin_Debug_LogResult' + '403': + $ref: '#/components/responses/AccessDenied' + '500': + $ref: '#/components/responses/GenericError' /admin/geolite: get: tags: @@ -1945,6 +1970,49 @@ paths: $ref: '#/components/responses/RecordNotFound' '500': $ref: '#/components/responses/GenericError' + '/station/{station_id}/files/list': + get: + tags: + - 'Stations: Media' + description: 'List files in the media directory by path.' + operationId: getStationFileList + parameters: + - + $ref: '#/components/parameters/StationIdRequired' + - + name: currentDirectory + in: query + required: true + schema: + type: string + - + name: searchPhrase + in: query + schema: + type: string + nullable: true + - + name: flushCache + in: query + schema: + type: boolean + default: false + nullable: true + responses: + '200': + description: Success + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Api_FileList' + '403': + $ref: '#/components/responses/AccessDenied' + '404': + $ref: '#/components/responses/RecordNotFound' + '500': + $ref: '#/components/responses/GenericError' '/station/{station_id}/file/{id}/play': get: tags: