feat: API docs for /files (#24423)

Signed-off-by: -LAN- <laipz8200@outlook.com>

api/controllers/files/__init__.py

@@ -1,9 +1,20 @@
 from flask import Blueprint
+from flask_restx import Namespace
 
 from libs.external_api import ExternalApi
 
-bp = Blueprint("files", __name__)
+bp = Blueprint("files", __name__, url_prefix="/files")
-api = ExternalApi(bp)
 
+api = ExternalApi(
+    bp,
+    version="1.0",
+    title="Files API",
+    description="API for file operations including upload and preview",
+    doc="/docs",  # Enable Swagger UI at /files/docs
+)
+
+files_ns = Namespace("files", description="File operations")
 
 from . import image_preview, tool_files, upload
+
+api.add_namespace(files_ns)

api/controllers/files/image_preview.py

@@ -6,11 +6,12 @@ from werkzeug.exceptions import NotFound
 
 import services
 from controllers.common.errors import UnsupportedFileTypeError
-from controllers.files import api
+from controllers.files import files_ns
 from services.account_service import TenantService
 from services.file_service import FileService
 
 
+@files_ns.route("/<uuid:file_id>/image-preview")
 class ImagePreviewApi(Resource):
     """
     Deprecated
@@ -39,6 +40,7 @@ class ImagePreviewApi(Resource):
         return Response(generator, mimetype=mimetype)
 
 
+@files_ns.route("/<uuid:file_id>/file-preview")
 class FilePreviewApi(Resource):
     def get(self, file_id):
         file_id = str(file_id)
@@ -94,6 +96,7 @@ class FilePreviewApi(Resource):
         return response
 
 
+@files_ns.route("/workspaces/<uuid:workspace_id>/webapp-logo")
 class WorkspaceWebappLogoApi(Resource):
     def get(self, workspace_id):
         workspace_id = str(workspace_id)
@@ -112,8 +115,3 @@ class WorkspaceWebappLogoApi(Resource):
             raise UnsupportedFileTypeError()
 
         return Response(generator, mimetype=mimetype)
-
-
-api.add_resource(ImagePreviewApi, "/files/<uuid:file_id>/image-preview")
-api.add_resource(FilePreviewApi, "/files/<uuid:file_id>/file-preview")
-api.add_resource(WorkspaceWebappLogoApi, "/files/workspaces/<uuid:workspace_id>/webapp-logo")

api/controllers/files/tool_files.py

@@ -5,13 +5,14 @@ from flask_restx import Resource, reqparse
 from werkzeug.exceptions import Forbidden, NotFound
 
 from controllers.common.errors import UnsupportedFileTypeError
-from controllers.files import api
+from controllers.files import files_ns
 from core.tools.signature import verify_tool_file_signature
 from core.tools.tool_file_manager import ToolFileManager
 from models import db as global_db
 
 
-class ToolFilePreviewApi(Resource):
+@files_ns.route("/tools/<uuid:file_id>.<string:extension>")
+class ToolFileApi(Resource):
     def get(self, file_id, extension):
         file_id = str(file_id)
 
@@ -52,6 +53,3 @@ class ToolFilePreviewApi(Resource):
             response.headers["Content-Disposition"] = f"attachment; filename*=UTF-8''{encoded_filename}"
 
         return response
-
-
-api.add_resource(ToolFilePreviewApi, "/files/tools/<uuid:file_id>.<string:extension>")

api/controllers/files/upload.py

@@ -1,7 +1,9 @@
 from mimetypes import guess_extension
+from typing import Optional
 
-from flask import request
+from flask_restx import Resource, reqparse
-from flask_restx import Resource, marshal_with
+from flask_restx.api import HTTPStatus
+from werkzeug.datastructures import FileStorage
 from werkzeug.exceptions import Forbidden
 
 import services
@@ -10,39 +12,76 @@ from controllers.common.errors import (
     UnsupportedFileTypeError,
 )
 from controllers.console.wraps import setup_required
-from controllers.files import api
+from controllers.files import files_ns
 from controllers.inner_api.plugin.wraps import get_user
 from core.file.helpers import verify_plugin_file_signature
 from core.tools.tool_file_manager import ToolFileManager
-from fields.file_fields import file_fields
+from fields.file_fields import build_file_model
+
+# Define parser for both documentation and validation
+upload_parser = reqparse.RequestParser()
+upload_parser.add_argument("file", location="files", type=FileStorage, required=True, help="File to upload")
+upload_parser.add_argument(
+    "timestamp", type=str, required=True, location="args", help="Unix timestamp for signature verification"
+)
+upload_parser.add_argument(
+    "nonce", type=str, required=True, location="args", help="Random string for signature verification"
+)
+upload_parser.add_argument(
+    "sign", type=str, required=True, location="args", help="HMAC signature for request validation"
+)
+upload_parser.add_argument("tenant_id", type=str, required=True, location="args", help="Tenant identifier")
+upload_parser.add_argument("user_id", type=str, required=False, location="args", help="User identifier")
 
 
+@files_ns.route("/upload/for-plugin")
 class PluginUploadFileApi(Resource):
     @setup_required
-    @marshal_with(file_fields)
+    @files_ns.expect(upload_parser)
+    @files_ns.doc("upload_plugin_file")
+    @files_ns.doc(description="Upload a file for plugin usage with signature verification")
+    @files_ns.doc(
+        responses={
+            201: "File uploaded successfully",
+            400: "Invalid request parameters",
+            403: "Forbidden - Invalid signature or missing parameters",
+            413: "File too large",
+            415: "Unsupported file type",
+        }
+    )
+    @files_ns.marshal_with(build_file_model(files_ns), code=HTTPStatus.CREATED)
     def post(self):
-        # get file from request
+        """Upload a file for plugin usage.
-        file = request.files["file"]
 
-        timestamp = request.args.get("timestamp")
+        Accepts a file upload with signature verification for security.
-        nonce = request.args.get("nonce")
+        The file must be accompanied by valid timestamp, nonce, and signature parameters.
-        sign = request.args.get("sign")
-        tenant_id = request.args.get("tenant_id")
-        if not tenant_id:
-            raise Forbidden("Invalid request.")
 
-        user_id = request.args.get("user_id")
+        Returns:
+            dict: File metadata including ID, URLs, and properties
+            int: HTTP status code (201 for success)
+
+        Raises:
+            Forbidden: Invalid signature or missing required parameters
+            FileTooLargeError: File exceeds size limit
+            UnsupportedFileTypeError: File type not supported
+        """
+        # Parse and validate all arguments
+        args = upload_parser.parse_args()
+
+        file: FileStorage = args["file"]
+        timestamp: str = args["timestamp"]
+        nonce: str = args["nonce"]
+        sign: str = args["sign"]
+        tenant_id: str = args["tenant_id"]
+        user_id: Optional[str] = args.get("user_id")
         user = get_user(tenant_id, user_id)
 
-        filename = file.filename
+        filename: Optional[str] = file.filename
-        mimetype = file.mimetype
+        mimetype: Optional[str] = file.mimetype
 
         if not filename or not mimetype:
             raise Forbidden("Invalid request.")
 
-        if not timestamp or not nonce or not sign:
-            raise Forbidden("Invalid request.")
-
         if not verify_plugin_file_signature(
             filename=filename,
             mimetype=mimetype,
@@ -88,6 +127,3 @@ class PluginUploadFileApi(Resource):
             raise FileTooLargeError(file_too_large_error.description)
         except services.errors.file.UnsupportedFileTypeError:
             raise UnsupportedFileTypeError()
-
-
-api.add_resource(PluginUploadFileApi, "/files/upload/for-plugin")