Add run-sync and file list endpoint docs.

igecloudsdev · Mar 8, 2025 · 30e97c8 · 30e97c8
1 parent 9886bdc
commit 30e97c8
Show file tree

Hide file tree

Showing 3 changed files with 144 additions and 9 deletions.
diff --git 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
@@ -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
@@ -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: