Feature | Extend Swagger Coverage for controller OAuth2ChunkedFilesApiController

app/Http/Controllers/Apis/Protected/Main/OAuth2ChunkedFilesApiController.php

@@ -1,4 +1,5 @@
-<?php namespace App\Http\Controllers;
+<?php
+namespace App\Http\Controllers;
 /**
  * Copyright 2020 OpenStack Foundation
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,8 +13,10 @@
  * limitations under the License.
  **/
 use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Response;
 use Illuminate\Http\UploadedFile;
 use Illuminate\Support\Facades\Storage;
+use OpenApi\Attributes as OA;
 use Pion\Laravel\ChunkUpload\Exceptions\UploadMissingFileException;
 use Pion\Laravel\ChunkUpload\Handler\AbstractHandler;
 use Pion\Laravel\ChunkUpload\Receiver\FileReceiver;
@@ -33,6 +36,35 @@ class OAuth2ChunkedFilesApiController extends UploadController
      * @throws UploadMissingFileException
      *
      */
+    #[OA\Post(
+        path: "/api/public/v1/files/upload",
+        description: "Upload files using chunked upload mechanism. Supports large file uploads by splitting them into smaller chunks. The endpoint handles both complete uploads and chunked progress updates.",
+        summary: 'Upload file with chunked upload support',
+        operationId: 'uploadChunkedFile',
+        tags: ['Files'],
+        requestBody: new OA\RequestBody(
+            required: true,
+            content: new OA\MediaType(
+                mediaType: 'multipart/form-data',
+                schema: new OA\Schema(ref: '#/components/schemas/ChunkedFileUploadRequest')
+            )
+        ),
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Success - Upload in progress (chunk uploaded)',
+                content: new OA\JsonContent(ref: '#/components/schemas/ChunkedFileUploadProgressResponse')
+            ),
+            new OA\Response(
+                response: 201,
+                description: 'Success - Upload complete (all chunks received)',
+                content: new OA\JsonContent(ref: '#/components/schemas/ChunkedFileUploadCompleteResponse')
+            ),
+            new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request - Invalid file or missing parameters"),
+            new OA\Response(response: Response::HTTP_UNPROCESSABLE_ENTITY, description: "Unprocessable Entity - Upload missing file exception"),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error - Upload failed")
+        ]
+    )]
     public function uploadFile(FileReceiver $receiver)
     {
         // check if the upload is success, throw exception or return response you need
@@ -57,4 +89,4 @@ public function uploadFile(FileReceiver $receiver)
         ]);
     }
 
-}
+}

app/Swagger/schemas.php

@@ -351,3 +351,56 @@ class RSVPUpdateRequestSchema_{
     ]
 )]
 class RSVPAdminAddRequestSchema {}
+
+#[OA\Schema(
+    schema: 'ChunkedFileUploadProgressResponse',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'done', type: 'number', format: 'float', example: 45.5, description: 'Upload progress percentage (0-100)'),
+    ]
+)]
+class ChunkedFileUploadProgressResponseSchema {}
+
+#[OA\Schema(
+    schema: 'ChunkedFileUploadCompleteResponse',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'path', type: 'string', example: 'upload/image-jpeg/2025-09-30/', description: 'Directory path where the file was saved'),
+        new OA\Property(property: 'name', type: 'string', example: 'myfile_abc123def456.jpg', description: 'Generated filename with timestamp hash'),
+        new OA\Property(property: 'mime_type', type: 'string', example: 'image-jpeg', description: 'MIME type of the uploaded file (slashes replaced with hyphens)'),
+    ]
+)]
+class ChunkedFileUploadCompleteResponseSchema {}
+
+#[OA\Schema(
+    schema: 'ChunkedFileUploadRequest',
+    type: 'object',
+    required: ['file'],
+    properties: [
+        new OA\Property(
+            property: 'file',
+            type: 'string',
+            format: 'binary',
+            description: 'File to upload (can be a chunk of a larger file)'
+        ),
+        new OA\Property(
+            property: 'resumableChunkNumber',
+            type: 'integer',
+            description: 'Current chunk number (for resumable.js library)',
+            example: 1
+        ),
+        new OA\Property(
+            property: 'resumableTotalChunks',
+            type: 'integer',
+            description: 'Total number of chunks (for resumable.js library)',
+            example: 5
+        ),
+        new OA\Property(
+            property: 'resumableIdentifier',
+            type: 'string',
+            description: 'Unique identifier for the file upload session (for resumable.js library)',
+            example: '12345-myfile-jpg'
+        ),
+    ]
+)]
+class ChunkedFileUploadRequestSchema {}