feat: Extend Swagger Coverage for controller UploadController

Author: matiasperrone-exo

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

@@ -11,9 +11,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  **/
+use Illuminate\Http\Response;
 use Illuminate\Routing\Controller as BaseController;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\Config;
+use OpenApi\Attributes as OA;
 use Pion\Laravel\ChunkUpload\Exceptions\UploadFailedException;
 use Illuminate\Support\Facades\Storage;
 use Illuminate\Http\Request;
@@ -28,16 +30,45 @@
  */
 class UploadController extends BaseController
 {
-    /**
-     * Handles the file upload
-     *
-     * @param Request $request
-     *
-     * @return JsonResponse
-     *
-     * @throws UploadMissingFileException
-     * @throws UploadFailedException
-     */
+    #[OA\Post(
+        path: '/api/v1/files/upload',
+        summary: 'Upload file with chunked support',
+        description: 'Handles file uploads with support for chunked uploads. Returns file metadata on completion or upload progress for chunks.',
+        security: [['bearer' => []]],
+        tags: ['files'],
+        requestBody: new OA\RequestBody(
+            required: true,
+            content: new OA\MediaType(
+                mediaType: 'multipart/form-data',
+                schema: new OA\Schema(
+                    required: ['file'],
+                    properties: [
+                        new OA\Property(
+                            property: 'file',
+                            type: 'string',
+                            format: 'binary',
+                            description: 'File to upload'
+                        ),
+                    ]
+                )
+            )
+        ),
+        responses: [
+            new OA\Response(
+                response: Response::HTTP_OK,
+                description: 'File uploaded successfully or chunk progress',
+                content: new OA\JsonContent(
+                    oneOf: [
+                        new OA\Schema(ref: '#/components/schemas/FileUploadCompleteResponse'),
+                        new OA\Schema(ref: '#/components/schemas/FileUploadProgressResponse'),
+                    ]
+                )
+            ),
+            new OA\Response(response: Response::HTTP_BAD_REQUEST, description: 'Bad Request'),
+            new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: 'Unauthorized'),
+            new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: 'Server Error'),
+        ]
+    )]
     public function upload(Request $request) {
         // create the file receiver
         $receiver = new FileReceiver("file", $request, HandlerFactory::classFromRequest($request));

app/Swagger/schemas.php

@@ -599,3 +599,24 @@ class PaymentGatewayProfileUpdateRequestSchema
     ]
 )]
 class PaginatedUserStoriesResponseSchema {}
+
+#[OA\Schema(
+    schema: 'FileUploadCompleteResponse',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'path', type: 'string', example: 'upload/application-pdf/2025-10-24/', description: 'File path'),
+        new OA\Property(property: 'name', type: 'string', example: 'document_abc123def456.pdf', description: 'Generated filename'),
+        new OA\Property(property: 'mime_type', type: 'string', example: 'application-pdf', description: 'MIME type (normalized with dashes)'),
+    ]
+)]
+class FileUploadCompleteResponseSchema {}
+
+#[OA\Schema(
+    schema: 'FileUploadProgressResponse',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'done', type: 'number', format: 'float', example: 45.5, description: 'Upload progress percentage'),
+        new OA\Property(property: 'status', type: 'boolean', example: true, description: 'Upload status'),
+    ]
+)]
+class FileUploadProgressResponseSchema {}