[pull] main from AzuraCast:main

backend/src/Controller/Api/Admin/Debug/ClearCacheAction.php

@@ -9,11 +9,23 @@
 use App\Entity\Api\Status;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Put(
+        path: '/admin/debug/clear-cache',
+        operationId: 'adminDebugClearCache',
+        description: 'Clear the application cache (Redis).',
+        tags: [OpenApi::TAG_ADMIN_DEBUG],
+        responses: [
+            new OpenApi\Response\Success(),
+            new OpenApi\Response\AccessDenied(),
+            new OpenApi\Response\GenericError(),
+        ]
+    ),
+]
 final class ClearCacheAction implements SingleActionInterface
 {
     public function __construct(

backend/src/Controller/Api/Admin/Debug/ClearQueueAction.php

@@ -10,11 +10,35 @@
 use App\Http\ServerRequest;
 use App\MessageQueue\QueueManagerInterface;
 use App\MessageQueue\QueueNames;
+use App\OpenApi;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Put(
+        path: '/admin/debug/clear-queue/{queue}',
+        operationId: 'adminDebugClearQueue',
+        description: 'Clear the specified message queue.',
+        tags: [OpenApi::TAG_ADMIN_DEBUG],
+        parameters: [
+            new OA\Parameter(
+                name: 'queue',
+                description: 'Message queue type.',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(
+                    type: 'string',
+                    enum: QueueNames::class
+                )
+            ),
+        ],
+        responses: [
+            new OpenApi\Response\Success(),
+            new OpenApi\Response\AccessDenied(),
+            new OpenApi\Response\GenericError(),
+        ]
+    ),
+]
 final class ClearQueueAction implements SingleActionInterface
 {
     public function __construct(

backend/src/Controller/Api/Admin/Debug/ClearStationQueueAction.php

@@ -6,17 +6,37 @@
 
 use App\Container\LoggerAwareTrait;
 use App\Controller\SingleActionInterface;
+use App\Entity\Api\Admin\Debug\LogResult;
 use App\Entity\Repository\StationQueueRepository;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Radio\AutoDJ\Queue;
 use Monolog\Handler\TestHandler;
 use Monolog\Level;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Put(
+        path: '/admin/debug/station/{station_id}/clearqueue',
+        operationId: 'adminDebugClearStationQueue',
+        description: 'Clear the upcoming song queue and generate a new one.',
+        tags: [OpenApi::TAG_ADMIN_DEBUG],
+        parameters: [
+            new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED),
+        ],
+        responses: [
+            new OpenApi\Response\Success(
+                content: new OA\JsonContent(
+                    ref: LogResult::class
+                )
+            ),
+            new OpenApi\Response\AccessDenied(),
+            new OpenApi\Response\GenericError(),
+        ]
+    ),
+]
 final class ClearStationQueueAction implements SingleActionInterface
 {
     use LoggerAwareTrait;
@@ -45,8 +65,8 @@ public function __invoke(
             $this->logger->popHandler();
         }
 
-        return $response->withJson([
-            'logs' => $testHandler->getRecords(),
-        ]);
+        return $response->withJson(
+            LogResult::fromTestHandlerRecords($testHandler->getRecords())
+        );
     }
 }

backend/src/Controller/Api/Admin/Debug/NextSongAction.php

@@ -6,16 +6,36 @@
 
 use App\Container\LoggerAwareTrait;
 use App\Controller\SingleActionInterface;
+use App\Entity\Api\Admin\Debug\LogResult;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Radio\AutoDJ\Annotations;
 use Monolog\Handler\TestHandler;
 use Monolog\Level;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Put(
+        path: '/admin/debug/station/{station_id}/nextsong',
+        operationId: 'adminDebugStationNextSong',
+        description: 'Get the next song to be played by the AutoDJ for a given station.',
+        tags: [OpenApi::TAG_ADMIN_DEBUG],
+        parameters: [
+            new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED),
+        ],
+        responses: [
+            new OpenApi\Response\Success(
+                content: new OA\JsonContent(
+                    ref: LogResult::class
+                )
+            ),
+            new OpenApi\Response\AccessDenied(),
+            new OpenApi\Response\GenericError(),
+        ]
+    ),
+]
 final class NextSongAction implements SingleActionInterface
 {
     use LoggerAwareTrait;
@@ -42,8 +62,8 @@ public function __invoke(
         ]);
         $this->logger->popHandler();
 
-        return $response->withJson([
-            'logs' => $testHandler->getRecords(),
-        ]);
+        return $response->withJson(
+            LogResult::fromTestHandlerRecords($testHandler->getRecords())
+        );
     }
 }

backend/src/Controller/Api/Admin/Debug/NowPlayingAction.php

@@ -6,16 +6,36 @@
 
 use App\Container\LoggerAwareTrait;
 use App\Controller\SingleActionInterface;
+use App\Entity\Api\Admin\Debug\LogResult;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Sync\NowPlaying\Task\NowPlayingTask;
 use Monolog\Handler\TestHandler;
 use Monolog\Level;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Put(
+        path: '/admin/debug/station/{station_id}/nowplaying',
+        operationId: 'adminDebugStationNowPlaying',
+        description: 'Generate the raw Now Playing data for a given station.',
+        tags: [OpenApi::TAG_ADMIN_DEBUG],
+        parameters: [
+            new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED),
+        ],
+        responses: [
+            new OpenApi\Response\Success(
+                content: new OA\JsonContent(
+                    ref: LogResult::class
+                )
+            ),
+            new OpenApi\Response\AccessDenied(),
+            new OpenApi\Response\GenericError(),
+        ]
+    ),
+]
 final class NowPlayingAction implements SingleActionInterface
 {
     use LoggerAwareTrait;
@@ -40,8 +60,8 @@ public function __invoke(
             $this->logger->popHandler();
         }
 
-        return $response->withJson([
-            'logs' => $testHandler->getRecords(),
-        ]);
+        return $response->withJson(
+            LogResult::fromTestHandlerRecords($testHandler->getRecords())
+        );
     }
 }

backend/src/Controller/Api/Admin/SendTestMessageAction.php

@@ -10,17 +10,29 @@
 use App\Exception\ValidationException;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Service\Mail;
 use App\Utilities\Types;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 use Symfony\Component\Mailer\Exception\TransportException;
 use Symfony\Component\Validator\Constraints\Email;
 use Symfony\Component\Validator\Constraints\Required;
 use Symfony\Component\Validator\Validator\ValidatorInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Post(
+        path: '/admin/send-test-message',
+        operationId: 'adminSendTestEmail',
+        description: 'Send a test e-mail to confirm mail delivery settings.',
+        tags: [OpenApi::TAG_ADMIN],
+        responses: [
+            new OpenApi\Response\Success(),
+            new OpenApi\Response\AccessDenied(),
+            new OpenApi\Response\GenericError(),
+        ]
+    ),
+]
 final class SendTestMessageAction implements SingleActionInterface
 {
     public function __construct(

backend/src/Controller/Api/NowPlayingArtAction.php

@@ -10,11 +10,26 @@
 use App\Entity\Api\NowPlaying\NowPlaying;
 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: '/nowplaying/{station_id}/art',
+        operationId: 'getStationNowPlayingArt',
+        description: 'Always redirects to the current art for the given station.',
+        security: [],
+        tags: [OpenApi::TAG_NOW_PLAYING],
+        parameters: [
+            new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED),
+        ],
+        responses: [
+            new OpenApi\Response\Redirect(),
+            new OpenApi\Response\NotFound(),
+        ]
+    )
+]
 final class NowPlayingArtAction implements SingleActionInterface
 {
     public function __construct(

backend/src/Controller/Api/OpenApiAction.php

@@ -8,12 +8,33 @@
 use App\Controller\SingleActionInterface;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Version;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Get(
+        path: '/openapi.yml',
+        operationId: 'getOpenApiSpec',
+        description: 'Returns the OpenAPI specification document for this installation.',
+        security: [],
+        tags: [OpenApi::TAG_MISC],
+        responses: [
+            new OpenApi\Response\SuccessWithDownload(
+                description: 'Success',
+                content: new OA\MediaType(
+                    mediaType: 'text/x-yaml',
+                    schema: new OA\Schema(
+                        description: 'The OpenAPI specification document for this installation.',
+                        type: 'string',
+                        format: 'binary'
+                    )
+                )
+            ),
+        ]
+    )
+]
 final class OpenApiAction implements SingleActionInterface
 {
     public function __construct(

backend/src/Controller/Api/PrometheusAction.php

@@ -9,18 +9,38 @@
 use App\Controller\SingleActionInterface;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Service\ServerStats;
 use Brick\Math\BigDecimal;
 use Brick\Math\BigInteger;
 use Brick\Math\RoundingMode;
+use OpenApi\Attributes as OA;
 use Prometheus\CollectorRegistry;
 use Prometheus\RenderTextFormat;
 use Prometheus\Storage\InMemory;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Get(
+        path: '/prometheus',
+        operationId: 'getPrometheus',
+        description: 'Returns the Prometheus measurements for this installation.',
+        tags: [OpenApi::TAG_MISC],
+        responses: [
+            new OpenApi\Response\SuccessWithDownload(
+                description: 'Success',
+                content: new OA\MediaType(
+                    mediaType: 'text/plain',
+                    schema: new OA\Schema(
+                        description: 'The Prometheus measurements for this installation.',
+                        type: 'string',
+                        format: 'binary'
+                    )
+                )
+            ),
+        ]
+    )
+]
 final class PrometheusAction implements SingleActionInterface
 {
     use EntityManagerAwareTrait;