swagger part 1

2025-08-05 07:03:35 -07:00
parent 56fb9b4ab6
commit 3de3d0a7b3
27 changed files with 3128 additions and 92 deletions
@@ -448,6 +448,158 @@ paths:
        "500":
          $ref: "#/components/responses/InternalError"

+  /client/{id}/document/batch:
+    parameters:
+      - $ref: "#/components/parameters/ClientID"
+    post:
+      operationId: uploadDocumentBatch
+      tags:
+        - DocumentsService
+      summary: Upload multiple PDF documents as ZIP archive
+      description: Upload a ZIP archive containing multiple PDF documents for async batch processing
+      security:
+        - jwtAuth: []
+      requestBody:
+        required: true
+        description: ZIP archive containing PDF documents
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required:
+                - archive
+              properties:
+                archive:
+                  type: string
+                  format: binary
+                  maxLength: 1073741824  # 1GB limit for ZIP files
+                  description: The file to be uploaded as a ZIP archive
+            encoding:
+              archive:
+                contentType: application/zip
+                style: form
+                explode: false
+      responses:
+        "202":
+          description: Batch upload accepted for processing
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BatchUploadResponse"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+        "500":
+          $ref: "#/components/responses/InternalError"
+    get:
+      operationId: listDocumentBatches
+      tags:
+        - DocumentsService
+      summary: List batch uploads for a client
+      description: Retrieves a list of batch uploads for the specified client
+      security:
+        - jwtAuth: []
+      parameters:
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            format: int32
+            minimum: 1
+            maximum: 100
+            default: 20
+          description: Maximum number of items to return
+        - in: query
+          name: offset
+          schema:
+            type: integer
+            format: int32
+            minimum: 0
+            maximum: 2147483647
+            default: 0
+          description: Number of items to skip
+      responses:
+        "200":
+          description: List of batch uploads
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BatchUploadList"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /client/{id}/document/batch/{batch_id}:
+    parameters:
+      - $ref: "#/components/parameters/ClientID"
+      - $ref: "#/components/parameters/BatchID"
+    get:
+      operationId: getDocumentBatch
+      tags:
+        - DocumentsService
+      summary: Get batch upload status
+      description: Retrieves detailed status information for a specific batch upload
+      security:
+        - jwtAuth: []
+      responses:
+        "200":
+          description: Batch upload details
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BatchUploadDetails"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+        "500":
+          $ref: "#/components/responses/InternalError"
+    delete:
+      operationId: cancelDocumentBatch
+      tags:
+        - DocumentsService
+      summary: Cancel a batch upload
+      description: Cancels a batch upload that is currently processing
+      security:
+        - jwtAuth: []
+      responses:
+        "204":
+          description: Batch upload cancelled successfully
+          headers:
+            RateLimit:
+              $ref: "#/components/headers/RateLimit"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
  /document/{id}:
    parameters:
      - $ref: "#/components/parameters/DocumentID"
@@ -723,6 +875,14 @@ components:
        $ref: "#/components/schemas/DocumentID"
      description: The document ID.

+    BatchID:
+      in: path
+      name: batch_id
+      required: true
+      schema:
+        $ref: "#/components/schemas/BatchID"
+      description: The batch upload ID.
+
  headers:
    RateLimit:
      schema:
@@ -806,6 +966,16 @@ components:
          schema:
            $ref: "#/components/schemas/ErrorMessage"

+    NotFound:
+      description: Resource not found.
+      headers:
+        RateLimit:
+          $ref: "#/components/headers/RateLimit"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorMessage"
+
  schemas:
    # Query API schemas
    ClientID:
@@ -836,6 +1006,151 @@ components:
      example: 019580de-4d51-713c-98ee-464e83811f13
      maxLength: 36

+    BatchID:
+      type: string
+      format: uuid
+      description: The batch upload id.
+      example: 019580df-ef65-7676-8de9-94435a93337a
+      maxLength: 36
+
+    BatchStatus:
+      type: string
+      enum:
+        - processing
+        - completed
+        - failed
+        - cancelled
+      description: The status of a batch upload
+
+    BatchUploadResponse:
+      type: object
+      description: Response returned when a batch upload is accepted for processing
+      required:
+        - batch_id
+        - status
+        - status_url
+      properties:
+        batch_id:
+          $ref: "#/components/schemas/BatchID"
+        status:
+          $ref: "#/components/schemas/BatchStatus"
+        status_url:
+          type: string
+          format: uri-reference
+          maxLength: 512
+          description: URL to check batch status
+          example: "/client/AAA/document/batch/019580df-ef65-7676-8de9-94435a93337a"
+
+    BatchUploadSummary:
+      type: object
+      description: Summary information about a batch upload
+      required:
+        - batch_id
+        - client_id
+        - original_filename
+        - status
+        - total_documents
+        - processed_documents
+        - failed_documents
+        - invalid_type_documents
+        - progress_percent
+        - created_at
+      properties:
+        batch_id:
+          $ref: "#/components/schemas/BatchID"
+        client_id:
+          $ref: "#/components/schemas/ClientID"
+        original_filename:
+          type: string
+          maxLength: 4096
+          pattern: "^.+$"
+          description: Original filename of the uploaded ZIP archive
+          example: "documents.zip"
+        status:
+          $ref: "#/components/schemas/BatchStatus"
+        total_documents:
+          type: integer
+          format: int32
+          minimum: 0
+          maximum: 2147483647
+          description: Total number of documents in the batch
+          example: 100
+        processed_documents:
+          type: integer
+          format: int32
+          minimum: 0
+          maximum: 2147483647
+          description: Number of documents processed so far
+          example: 42
+        failed_documents:
+          type: integer
+          format: int32
+          minimum: 0
+          maximum: 2147483647
+          description: Number of documents that failed processing
+          example: 2
+        invalid_type_documents:
+          type: integer
+          format: int32
+          minimum: 0
+          maximum: 2147483647
+          description: Number of non-PDF files found in archive
+          example: 1
+        progress_percent:
+          type: integer
+          format: int32
+          minimum: 0
+          maximum: 100
+          description: Processing progress percentage
+          example: 42
+        created_at:
+          type: string
+          format: date-time
+          maxLength: 50
+          description: When the batch upload was created
+        completed_at:
+          type: string
+          format: date-time
+          maxLength: 50
+          nullable: true
+          description: When the batch upload completed processing
+
+    BatchUploadDetails:
+      description: Detailed information about a batch upload including failed filenames
+      allOf:
+        - $ref: "#/components/schemas/BatchUploadSummary"
+        - type: object
+          properties:
+            failed_filenames:
+              type: array
+              maxItems: 10000
+              items:
+                type: string
+                maxLength: 4096
+                pattern: "^.+$"
+              description: List of filenames that failed processing
+              example: ["doc3.pdf", "doc17.pdf"]
+
+    BatchUploadList:
+      type: object
+      description: List of batch uploads for a client
+      required:
+        - batches
+        - total_count
+      properties:
+        batches:
+          type: array
+          maxItems: 100
+          items:
+            $ref: "#/components/schemas/BatchUploadSummary"
+        total_count:
+          type: integer
+          format: int32
+          minimum: 0
+          maximum: 2147483647
+          description: Total number of batches for this client
+          example: 25
+
    ClientName:
      type: string
      description: The client name