Document even more API endpoints.

igecloudsdev · Mar 7, 2025 · 573cb8f · 573cb8f
1 parent 0c2ae3d
commit 573cb8f
Show file tree

Hide file tree

Showing 11 changed files with 447 additions and 29 deletions.
diff --git a/backend/src/Controller/Api/Admin/Acme/CertificateLogAction.php b/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;

diff --git a/backend/src/Controller/Api/Admin/Backups/DeleteAction.php b/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(

diff --git a/backend/src/Controller/Api/Admin/Backups/DownloadAction.php b/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(

diff --git a/backend/src/Controller/Api/Admin/Backups/GetAction.php b/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(

diff --git a/backend/src/Controller/Api/Admin/Backups/GetLogAction.php b/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;

diff --git a/backend/src/Controller/Api/Stations/Streamers/Art/DeleteArtAction.php b/backend/src/Controller/Api/Stations/Streamers/Art/DeleteArtAction.php
@@ -9,11 +9,32 @@
 use App\Entity\Repository\StationStreamerRepository;
 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}/streamer/{id}/art',
+    operationId: 'deleteStreamerArt',
+    description: 'Removes the default album art for a streamer.',
+    tags: [OpenApi::TAG_STATIONS_STREAMERS],
+    parameters: [
+        new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED),
+        new OA\Parameter(
+            name: 'id',
+            description: 'Streamer ID',
+            in: 'path',
+            required: true,
+            schema: new OA\Schema(type: 'integer', format: 'int64')
+        ),
+    ],
+    responses: [
+        new OpenApi\Response\Success(),
+        new OpenApi\Response\AccessDenied(),
+        new OpenApi\Response\NotFound(),
+        new OpenApi\Response\GenericError(),
+    ]
+)]
 final class DeleteArtAction implements SingleActionInterface
 {
     public function __construct(

diff --git a/backend/src/Controller/Api/Stations/Streamers/Art/GetArtAction.php b/backend/src/Controller/Api/Stations/Streamers/Art/GetArtAction.php
@@ -10,11 +10,34 @@
 use App\Flysystem\StationFilesystems;
 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: '/station/{station_id}/streamer/{id}/art',
+    operationId: 'getStreamerArt',
+    description: 'Gets the default album art for a streamer.',
+    security: [],
+    tags: [OpenApi::TAG_STATIONS_STREAMERS],
+    parameters: [
+        new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED),
+        new OA\Parameter(
+            name: 'id',
+            description: 'Streamer ID',
+            in: 'path',
+            required: true,
+            schema: new OA\Schema(type: 'integer', format: 'int64')
+        ),
+    ],
+    responses: [
+        new OpenApi\Response\SuccessWithImage(),
+        new OpenApi\Response\Redirect(),
+        new OpenApi\Response\AccessDenied(),
+        new OpenApi\Response\NotFound(),
+        new OpenApi\Response\GenericError(),
+    ]
+)]
 final class GetArtAction implements SingleActionInterface
 {
     public function __construct(

diff --git a/backend/src/Controller/Api/Stations/Streamers/Art/PostArtAction.php b/backend/src/Controller/Api/Stations/Streamers/Art/PostArtAction.php
@@ -9,12 +9,34 @@
 use App\Entity\Repository\StationStreamerRepository;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Service\Flow;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[OA\Post(
+    path: '/station/{station_id}/streamer/{id}/art',
+    operationId: 'postStreamerArt',
+    description: 'Sets the default album art for a streamer.',
+    requestBody: new OA\RequestBody(ref: OpenApi::REF_REQUEST_BODY_FLOW_FILE_UPLOAD),
+    tags: [OpenApi::TAG_STATIONS_STREAMERS],
+    parameters: [
+        new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED),
+        new OA\Parameter(
+            name: 'id',
+            description: 'Streamer ID',
+            in: 'path',
+            required: true,
+            schema: new OA\Schema(type: 'integer', format: 'int64')
+        ),
+    ],
+    responses: [
+        new OpenApi\Response\Success(),
+        new OpenApi\Response\AccessDenied(),
+        new OpenApi\Response\NotFound(),
+        new OpenApi\Response\GenericError(),
+    ]
+)]
 final class PostArtAction implements SingleActionInterface
 {
     public function __construct(

diff --git a/backend/src/Controller/Api/Stations/Webhooks/TestLogAction.php b/backend/src/Controller/Api/Stations/Webhooks/TestLogAction.php
@@ -7,15 +7,49 @@
 use App\Controller\Api\Traits\HasLogViewer;
 use App\Controller\SingleActionInterface;
 use App\Entity\Api\Error;
+use App\Entity\Api\LogContents;
 use App\Entity\Repository\StationWebhookRepository;
 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: '/station/{station_id}/webhooks/{id}/test-log/{path}',
+        operationId: 'getWebhookTestLog',
+        description: 'View a specific webhook test dispatch log contents.',
+        tags: [OpenApi::TAG_STATIONS_WEBHOOKS],
+        parameters: [
+            new OA\Parameter(ref: OpenApi::REF_STATION_ID_REQUIRED),
+            new OA\Parameter(
+                name: 'id',
+                description: 'Web Hook ID',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'integer', format: 'int64')
+            ),
+            new OA\Parameter(
+                name: 'path',
+                description: 'Log path as returned by the Test 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 TestLogAction implements SingleActionInterface
 {
     use HasLogViewer;

diff --git a/backend/src/OpenApi.php b/backend/src/OpenApi.php
@@ -54,6 +54,7 @@
             new OA\Tag(name: OpenApi::TAG_STATIONS_WEBHOOKS),
 
             new OA\Tag(name: OpenApi::TAG_ADMIN),
+            new OA\Tag(name: OpenApi::TAG_ADMIN_BACKUPS),
             new OA\Tag(name: OpenApi::TAG_ADMIN_CUSTOM_FIELDS),
             new OA\Tag(name: OpenApi::TAG_ADMIN_USERS),
             new OA\Tag(name: OpenApi::TAG_ADMIN_ROLES),
@@ -204,6 +205,7 @@ final class OpenApi
     ];
 
     public const string TAG_ADMIN = 'Administration: General';
+    public const string TAG_ADMIN_BACKUPS = 'Administration: Backups';
     public const string TAG_ADMIN_CUSTOM_FIELDS = 'Administration: Custom Fields';
     public const string TAG_ADMIN_USERS = 'Administration: Users';
     public const string TAG_ADMIN_ROLES = 'Administration: Roles';
@@ -213,6 +215,7 @@ final class OpenApi
 
     public const array TAG_GROUP_ADMIN = [
         self::TAG_ADMIN,
+        self::TAG_ADMIN_BACKUPS,
         self::TAG_ADMIN_CUSTOM_FIELDS,
         self::TAG_ADMIN_USERS,
         self::TAG_ADMIN_ROLES,