Document : documentation fixes and callback router (#456)

* function doc fixes and callback router

* small fix

Author: nishika26

backend/app/api/docs/documents/info.md

@@ -1 +1 @@
-Retrieve all information about a given document.
+Retrieve all information about a given document. If you set the ``include_url`` parameter to true, a signed URL will be included in the response, which is a clickable link to access the retrieved document. If you don't set it to true, the URL will not be included in the response.

backend/app/api/docs/documents/job_info.md

@@ -0,0 +1 @@
+Get the status and details of a document transformation job. If you set the ``include_url`` parameter to true, a signed URL will be included in the response, which is a clickable link to access the transformed document if the job has been successful. If you don't set it to true, the URL will not be included in the response.

backend/app/api/docs/documents/job_list.md

@@ -0,0 +1 @@
+Get the status and details of multiple document transformation jobs by IDs. If you set the ``include_url`` parameter to true, a signed URL will be included in the response, which is a clickable link to access the transformed document for successful jobs. If you don't set it to true, the URL will not be included in the response.

backend/app/api/docs/documents/list.md

@@ -1 +1 @@
-List documents uploaded to the AI platform.
+List documents uploaded to the AI platform.  If you set the ``include_url`` parameter to true, a signed URL will be included in the response, which is a clickable link to access the retrieved documents. If you don't set it to true, the URL will not be included in the response.

backend/app/api/docs/documents/upload.md

@@ -2,6 +2,7 @@ Upload a document to the AI platform.
 
 - If only a file is provided, the document will be uploaded and stored, and its ID will be returned.
 - If a target format is specified, a transformation job will also be created to transform document into target format in the background. The response will include both the uploaded document details and information about the transformation job.
+- If a callback URL is provided, you will receive a notification at that URL once the document transformation job is completed.
 
 ### Supported Transformations
 

backend/app/api/routes/doc_transformation_job.py

@@ -1,16 +1,15 @@
 from uuid import UUID
 import logging
 
-from fastapi import APIRouter, HTTPException, Query, Path
+from fastapi import APIRouter, Query, Path
 
 from app.api.deps import CurrentUserOrgProject, SessionDep
 from app.crud import DocTransformationJobCrud, DocumentCrud
 from app.models import (
     DocTransformationJobPublic,
     DocTransformationJobsPublic,
-    TransformedDocumentPublic,
 )
-from app.utils import APIResponse
+from app.utils import APIResponse, load_description
 from app.services.documents.helpers import build_job_schema, build_job_schemas
 from app.core.cloud import get_cloud_storage
 
@@ -21,7 +20,7 @@
 
 @router.get(
     "/{job_id}",
-    description="Get the status and details of a document transformation job.",
+    description=load_description("documents/job_info.md"),
     response_model=APIResponse[DocTransformationJobPublic],
 )
 def get_transformation_job(
@@ -53,7 +52,7 @@ def get_transformation_job(
 
 @router.get(
     "/",
-    description="Get the status and details of multiple document transformation jobs by IDs.",
+    description=load_description("documents/job_list.md"),
     response_model=APIResponse[DocTransformationJobsPublic],
 )
 def get_multiple_transformation_jobs(

backend/app/api/routes/documents.py

@@ -23,6 +23,7 @@
     DocumentUploadResponse,
     Message,
     TransformationJobInfo,
+    DocTransformationJobPublic,
 )
 from app.services.collections.helpers import pick_service_for_documennt
 from app.services.documents.helpers import (
@@ -36,6 +37,25 @@
 
 logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/documents", tags=["documents"])
+doctransformation_callback_router = APIRouter()
+
+
+@doctransformation_callback_router.post(
+    "{$callback_url}",
+    name="doctransformation_callback",
+)
+def doctransformation_callback_notification(
+    body: APIResponse[DocTransformationJobPublic],
+):
+    """
+    Callback endpoint specification for document transformation.
+
+    The callback will receive:
+    - On success: APIResponse with success=True and data containing DocTransformationJobPublic
+    - On failure: APIResponse with success=False and error message
+    - metadata field will always be included if provided in the request
+    """
+    ...
 
 
 @router.get(
@@ -73,6 +93,7 @@ def list_docs(
     "/",
     description=load_description("documents/upload.md"),
     response_model=APIResponse[DocumentUploadResponse],
+    callbacks=doctransformation_callback_router.routes,
 )
 async def upload_doc(
     session: SessionDep,