Add API docs for some playlist functions and the station profile endp…

…oint.
igecloudsdev · Mar 8, 2025 · 8b55db0 · 8b55db0
1 parent 573cb8f
commit 8b55db0
Show file tree

Hide file tree

Showing 7 changed files with 315 additions and 18 deletions.
diff --git a/backend/src/Controller/Api/Stations/Playlists/DeleteQueueAction.php b/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(

diff --git a/backend/src/Controller/Api/Stations/Playlists/EmptyAction.php b/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(

diff --git a/backend/src/Controller/Api/Stations/Playlists/ExportAction.php b/backend/src/Controller/Api/Stations/Playlists/ExportAction.php
@@ -8,12 +8,44 @@
 use App\Entity\Repository\StationPlaylistRepository;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use InvalidArgumentException;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[OA\Get(
+    path: '/station/{station_id}/playlist/{id}/export/{format}',
+    operationId: 'getExportPlaylist',
+    description: 'Export a playlist contents in standard media player playlist format.',
+    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')
+        ),
+        new OA\Parameter(
+            name: 'format',
+            description: 'Export Playlist Format',
+            in: 'path',
+            required: true,
+            schema: new OA\Schema(
+                type: 'string',
+                default: 'pls',
+                enum: ['pls', 'm3u']
+            )
+        ),
+    ],
+    responses: [
+        new OpenApi\Response\SuccessWithDownload(),
+        new OpenApi\Response\AccessDenied(),
+        new OpenApi\Response\NotFound(),
+        new OpenApi\Response\GenericError(),
+    ]
+)]
 final class ExportAction implements SingleActionInterface
 {
     public function __construct(

diff --git a/backend/src/Controller/Api/Stations/Playlists/ReshuffleAction.php b/backend/src/Controller/Api/Stations/Playlists/ReshuffleAction.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\Put(
+    path: '/station/{station_id}/playlist/{id}/reshuffle',
+    operationId: 'putReshufflePlaylist',
+    description: 'Re-shuffle a playlist whose playback order is "shuffled".',
+    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 ReshuffleAction implements SingleActionInterface
 {
     public function __construct(

diff --git a/backend/src/Controller/Api/Stations/Playlists/ToggleAction.php b/backend/src/Controller/Api/Stations/Playlists/ToggleAction.php
@@ -9,11 +9,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\Put(
+    path: '/station/{station_id}/playlist/{id}/toggle',
+    operationId: 'putTogglePlaylist',
+    description: 'Toggle a playlist between enabled and disabled status.',
+    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 ToggleAction implements SingleActionInterface
 {
     public function __construct(

diff --git a/backend/src/Controller/Api/Stations/ProfileAction.php b/backend/src/Controller/Api/Stations/ProfileAction.php
@@ -11,13 +11,31 @@
 use App\Entity\Repository\StationScheduleRepository;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Radio\Adapters;
 use GuzzleHttp\Psr7\Uri;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[
+    OA\Get(
+        path: '/station/{station_id}/profile',
+        operationId: 'getStationProfile',
+        description: 'Retrieve the profile of the given station.',
+        tags: [OpenApi::TAG_STATIONS],
+        parameters: [
+            new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED),
+        ],
+        responses: [
+            new OpenApi\Response\Success(
+                content: new OA\JsonContent(ref: StationProfile::class)
+            ),
+            new OpenApi\Response\AccessDenied(),
+            new OpenApi\Response\NotFound(),
+            new OpenApi\Response\GenericError(),
+        ]
+    )
+]
 final class ProfileAction implements SingleActionInterface
 {
     public function __construct(