[pull] main from AzuraCast:main

backend/src/Console/Command/Dev/GenerateApiDocsCommand.php

@@ -72,7 +72,7 @@ public function generate(
             $srcDir . '/Radio/Enums', // Enums
             $srcDir . '/Webhook/Enums', // Enums
         ], [
-            'Migrations',
+            'Migration',
         ]);
 
         $generator = new Generator($this->logger);

backend/src/Controller/Api/Admin/Acme/CertificateLogAction.php

@@ -6,14 +6,40 @@
 
 use App\Controller\Api\Traits\HasLogViewer;
 use App\Controller\SingleActionInterface;
+use App\Entity\Api\LogContents;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Utilities\File;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Get(
+        path: '/admin/acme-log/{path}',
+        operationId: 'adminAcmeViewLog',
+        description: 'View the logs of a manually run ACME certificate renewal.',
+        tags: [OpenApi::TAG_ADMIN],
+        parameters: [
+            new OA\Parameter(
+                name: 'path',
+                description: 'Log path as returned by the Run action.',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'string')
+            ),
+        ],
+        responses: [
+            new OpenApi\Response\Success(
+                content: new OA\JsonContent(
+                    ref: LogContents::class
+                )
+            ),
+            new OpenApi\Response\AccessDenied(),
+            new OpenApi\Response\GenericError(),
+        ]
+    ),
+]
 final class CertificateLogAction implements SingleActionInterface
 {
     use HasLogViewer;

backend/src/Controller/Api/Admin/Backups/DeleteAction.php

@@ -8,11 +8,32 @@
 use App\Flysystem\ExtendedFilesystemInterface;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Delete(
+        path: '/admin/backups/delete/{path}',
+        operationId: 'deleteBackup',
+        description: 'Delete a given backup.',
+        tags: [OpenApi::TAG_ADMIN_BACKUPS],
+        parameters: [
+            new OA\Parameter(
+                name: 'path',
+                description: 'Download path (base64-encoded "StorageLocationID | Path")',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'string')
+            ),
+        ],
+        responses: [
+            new OpenApi\Response\Success(),
+            new OpenApi\Response\AccessDenied(),
+            new OpenApi\Response\GenericError(),
+        ]
+    )
+]
 final class DeleteAction extends AbstractFileAction
 {
     public function __invoke(

backend/src/Controller/Api/Admin/Backups/DownloadAction.php

@@ -7,11 +7,32 @@
 use App\Flysystem\ExtendedFilesystemInterface;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Get(
+        path: '/admin/backups/download/{path}',
+        operationId: 'downloadBackup',
+        description: 'Download a given backup.',
+        tags: [OpenApi::TAG_ADMIN_BACKUPS],
+        parameters: [
+            new OA\Parameter(
+                name: 'path',
+                description: 'Download path (base64-encoded "StorageLocationID | Path")',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'string')
+            ),
+        ],
+        responses: [
+            new OpenApi\Response\SuccessWithDownload(),
+            new OpenApi\Response\AccessDenied(),
+            new OpenApi\Response\GenericError(),
+        ]
+    )
+]
 final class DownloadAction extends AbstractFileAction
 {
     public function __invoke(

backend/src/Controller/Api/Admin/Backups/GetAction.php

@@ -22,7 +22,7 @@
         path: '/admin/backups',
         operationId: 'getBackups',
         description: 'Return a list of all current backups.',
-        tags: [OpenApi::TAG_ADMIN],
+        tags: [OpenApi::TAG_ADMIN_BACKUPS],
         responses: [
             new OpenApi\Response\Success(
                 content: new OA\JsonContent(

backend/src/Controller/Api/Admin/Backups/GetLogAction.php

@@ -6,14 +6,40 @@
 
 use App\Controller\Api\Traits\HasLogViewer;
 use App\Controller\SingleActionInterface;
+use App\Entity\Api\LogContents;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Utilities\File;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Get(
+        path: '/admin/backups/log/{path}',
+        operationId: 'adminBackupsViewLog',
+        description: 'View a specific backup log contents.',
+        tags: [OpenApi::TAG_ADMIN_BACKUPS],
+        parameters: [
+            new OA\Parameter(
+                name: 'path',
+                description: 'Log path as returned by the Run action.',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'string')
+            ),
+        ],
+        responses: [
+            new OpenApi\Response\Success(
+                content: new OA\JsonContent(
+                    ref: LogContents::class
+                )
+            ),
+            new OpenApi\Response\AccessDenied(),
+            new OpenApi\Response\GenericError(),
+        ]
+    ),
+]
 final class GetLogAction implements SingleActionInterface
 {
     use HasLogViewer;

backend/src/Controller/Api/Admin/CustomAssets/GetCustomAssetAction.php

@@ -7,7 +7,7 @@
 use App\Assets\AssetTypes;
 use App\Container\EnvironmentAwareTrait;
 use App\Controller\SingleActionInterface;
-use App\Entity\Api\CustomAsset;
+use App\Entity\Api\UploadedRecordStatus;
 use App\Http\Response;
 use App\Http\ServerRequest;
 use App\OpenApi;
@@ -34,7 +34,7 @@ enum: AssetTypes::class
     responses: [
         new OpenApi\Response\Success(
             content: new OA\JsonContent(
-                ref: CustomAsset::class
+                ref: UploadedRecordStatus::class
             )
         ),
         new OpenApi\Response\AccessDenied(),
@@ -57,7 +57,7 @@ public function __invoke(
         $customAsset = AssetTypes::from($type)->createObject($this->environment);
 
         return $response->withJson(
-            new CustomAsset(
+            new UploadedRecordStatus(
                 $customAsset->isUploaded(),
                 $customAsset->getUrl()
             )

backend/src/Controller/Api/Stations/Art/GetArtAction.php

@@ -34,10 +34,10 @@
         ),
     ],
     responses: [
-        new OpenApi\Response\Success(
+        new OpenApi\Response\SuccessWithImage(
             description: 'The requested album artwork'
         ),
-        new OpenApi\Response\NotFound(
+        new OpenApi\Response\Redirect(
             description: 'Image not found; generic filler image.'
         ),
     ]

backend/src/Controller/Api/Stations/CustomAssets/GetCustomAssetAction.php

@@ -7,7 +7,7 @@
 use App\Assets\AssetTypes;
 use App\Container\EnvironmentAwareTrait;
 use App\Controller\SingleActionInterface;
-use App\Entity\Api\CustomAsset;
+use App\Entity\Api\UploadedRecordStatus;
 use App\Http\Response;
 use App\Http\ServerRequest;
 use App\OpenApi;
@@ -35,7 +35,7 @@ enum: AssetTypes::class
     responses: [
         new OpenApi\Response\Success(
             content: new OA\JsonContent(
-                ref: CustomAsset::class
+                ref: UploadedRecordStatus::class
             )
         ),
         new OpenApi\Response\AccessDenied(),
@@ -61,7 +61,7 @@ public function __invoke(
         );
 
         return $response->withJson(
-            new CustomAsset(
+            new UploadedRecordStatus(
                 $customAsset->isUploaded(),
                 $customAsset->getUrl(),
             )

backend/src/Controller/Api/Stations/Fallback/GetFallbackAction.php

@@ -6,6 +6,7 @@
 
 use App\Controller\SingleActionInterface;
 use App\Entity\Api\Error;
+use App\Entity\Api\UploadedRecordStatus;
 use App\Flysystem\StationFilesystems;
 use App\Http\Response;
 use App\Http\ServerRequest;
@@ -23,7 +24,9 @@
     ],
     responses: [
         new OpenApi\Response\Success(
-        /* TODO API Body */
+            content: new OA\JsonContent(
+                ref: UploadedRecordStatus::class
+            )
         ),
         new OpenApi\Response\AccessDenied(),
         new OpenApi\Response\NotFound(),
@@ -56,14 +59,14 @@ public function __invoke(
                     );
                 }
 
-                return $response->withJson([
-                    'hasRecord' => true,
-                    'links' => [
-                        'download' => $router->fromHere(
+                return $response->withJson(
+                    new UploadedRecordStatus(
+                        true,
+                        $router->fromHere(
                             routeParams: ['do' => 'download']
-                        ),
-                    ],
-                ]);
+                        )
+                    )
+                );
             }
         }
 
@@ -72,11 +75,11 @@ public function __invoke(
                 ->withJson(Error::notFound());
         }
 
-        return $response->withJson([
-            'hasRecord' => false,
-            'links' => [
-                'download' => null,
-            ],
-        ]);
+        return $response->withJson(
+            new UploadedRecordStatus(
+                false,
+                null,
+            )
+        );
     }
 }

backend/src/Controller/Api/Stations/Mounts/Intro/GetIntroAction.php

@@ -31,9 +31,7 @@
         ),
     ],
     responses: [
-        new OpenApi\Response\Success(
-        /* TODO API Body */
-        ),
+        new OpenApi\Response\SuccessWithDownload(),
         new OpenApi\Response\AccessDenied(),
         new OpenApi\Response\NotFound(),
         new OpenApi\Response\GenericError(),

backend/src/Controller/Api/Stations/Playlists/DeleteQueueAction.php

@@ -10,11 +10,32 @@
 use App\Entity\Repository\StationPlaylistRepository;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[OA\Delete(
+    path: '/station/{station_id}/playlist/{id}/queue',
+    operationId: 'deletePlaylistQueue',
+    description: 'Reset the internal playback queue of a shuffled, song-based playlist.',
+    tags: [OpenApi::TAG_STATIONS_PLAYLISTS],
+    parameters: [
+        new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED),
+        new OA\Parameter(
+            name: 'id',
+            description: 'Playlist ID',
+            in: 'path',
+            required: true,
+            schema: new OA\Schema(type: 'int', format: 'int64')
+        ),
+    ],
+    responses: [
+        new OpenApi\Response\Success(),
+        new OpenApi\Response\AccessDenied(),
+        new OpenApi\Response\NotFound(),
+        new OpenApi\Response\GenericError(),
+    ]
+)]
 final class DeleteQueueAction implements SingleActionInterface
 {
     public function __construct(

backend/src/Controller/Api/Stations/Playlists/EmptyAction.php

@@ -12,11 +12,32 @@
 use App\Exception;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[OA\Delete(
+    path: '/station/{station_id}/playlist/{id}/empty',
+    operationId: 'deleteEmptyPlaylist',
+    description: 'Empty the contents of a song-based playlist.',
+    tags: [OpenApi::TAG_STATIONS_PLAYLISTS],
+    parameters: [
+        new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED),
+        new OA\Parameter(
+            name: 'id',
+            description: 'Playlist ID',
+            in: 'path',
+            required: true,
+            schema: new OA\Schema(type: 'int', format: 'int64')
+        ),
+    ],
+    responses: [
+        new OpenApi\Response\Success(),
+        new OpenApi\Response\AccessDenied(),
+        new OpenApi\Response\NotFound(),
+        new OpenApi\Response\GenericError(),
+    ]
+)]
 final class EmptyAction implements SingleActionInterface
 {
     public function __construct(