openapi.yaml

openapi: 3.0.3
info:
  title: PDF Backend API
  version: 1.0.0
  description: |
    API de generation de documents PDF en batch.

    Cette specification couvre:
    - la creation de batchs de generation
    - le suivi de progression
    - le telechargement des PDFs
    - les endpoints d'observabilite et de sante
servers:
  - url: http://localhost:3000
    description: Local development

paths:
  /health:
    get:
      tags: [System]
      summary: Health check global (DB, Redis, queue)
      responses:
        "200":
          description: Service healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
        "503":
          description: Service unhealthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

  /metrics:
    get:
      tags: [Observability]
      summary: Prometheus metrics endpoint
      responses:
        "200":
          description: Prometheus text format
          content:
            text/plain:
              schema:
                type: string

  /api/documents/batch:
    post:
      tags: [Documents]
      summary: Create a PDF generation batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateBatchRequest"
            examples:
              sample:
                value:
                  userIds:
                    - user_1
                    - user_2
                    - user_3
      responses:
        "200":
          description: Batch created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateBatchResponse"
        "400":
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Database unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/documents/batch/{batchId}:
    get:
      tags: [Documents]
      summary: Get batch status and document list
      parameters:
        - name: batchId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Batch status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchStatusResponse"
        "400":
          description: Invalid batchId
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Batch not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Database unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/documents/{documentId}:
    get:
      tags: [Documents]
      summary: Download generated PDF
      parameters:
        - name: documentId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: PDF stream
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "400":
          description: Invalid documentId
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Document not found or PDF not ready
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: GridFS stream error
        "503":
          description: Database unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  schemas:
    CreateBatchRequest:
      type: object
      required: [userIds]
      properties:
        userIds:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            type: string
            minLength: 1

    CreateBatchResponse:
      type: object
      required: [batchId, status, totalDocuments, createdAt]
      properties:
        batchId:
          type: string
        status:
          type: string
          enum: [pending]
        totalDocuments:
          type: integer
        createdAt:
          type: string
          format: date-time

    BatchProgress:
      type: object
      required: [total, completed, failed, percentage]
      properties:
        total:
          type: integer
        completed:
          type: integer
        failed:
          type: integer
        percentage:
          type: number

    BatchDocument:
      type: object
      required: [documentId, userId, status]
      properties:
        documentId:
          type: string
        userId:
          type: string
        status:
          type: string
          enum: [pending, generating, completed, failed]
        generatedAt:
          type: string
          format: date-time
          nullable: true
        fileSize:
          type: string
          nullable: true
        retryCount:
          type: integer
          nullable: true
        error:
          type: string
          nullable: true

    BatchStatusResponse:
      type: object
      required: [batchId, status, progress, documents, estimatedTimeRemaining]
      properties:
        batchId:
          type: string
        status:
          type: string
          enum: [pending, processing, completed, failed, partially_completed]
        progress:
          $ref: "#/components/schemas/BatchProgress"
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        documents:
          type: array
          items:
            $ref: "#/components/schemas/BatchDocument"
        estimatedTimeRemaining:
          type: string
          nullable: true

    HealthCheckDatabase:
      type: object
      properties:
        status:
          type: string
        responseTime:
          type: string
        message:
          type: string

    HealthCheckRedis:
      type: object
      properties:
        status:
          type: string
        responseTime:
          type: string
        message:
          type: string

    HealthCheckQueue:
      type: object
      properties:
        status:
          type: string
        responseTime:
          type: string
        pendingJobs:
          type: integer
        activeJobs:
          type: integer
        failedJobs:
          type: integer
        message:
          type: string
        fallback:
          type: object
          properties:
            enabled:
              type: boolean
            size:
              type: integer
            maxSize:
              type: integer

    HealthResponse:
      type: object
      required: [status, timestamp]
      properties:
        status:
          type: string
          enum: [healthy, unhealthy]
        timestamp:
          type: string
          format: date-time
        totalResponseTime:
          type: string
        checks:
          type: object
          properties:
            database:
              $ref: "#/components/schemas/HealthCheckDatabase"
            redis:
              $ref: "#/components/schemas/HealthCheckRedis"
            queue:
              $ref: "#/components/schemas/HealthCheckQueue"

    ErrorResponse:
      type: object
      properties:
        message:
          type: string