openapi: 3.0.3
info:
  title: Patente Quiz API
  description: API per la simulazione dell'esame teorico patente B.
  version: 1.0.0
servers:
  - url: http://127.0.0.1:8000
    description: Local development server
tags:
  - name: Health
  - name: Questions
  - name: Images
paths:
  /api/health:
    get:
      tags: [Health]
      summary: Health check
      description: Restituisce lo stato del servizio e il numero di domande per lingua.
      responses:
        '200':
          description: Servizio operativo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                status: ok
                questions:
                  it: 1200
                  fr: 800
                  de: 800

  /api/questions/exam:
    get:
      tags: [Questions]
      summary: Genera un esame
      description: Restituisce 30 domande casuali vero/falso per la lingua richiesta.
      parameters:
        - name: language
          in: query
          required: false
          schema:
            type: string
            enum: [it, fr, de]
            default: it
      responses:
        '200':
          description: Esame generato
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExamResponse'
        '400':
          description: Lingua non supportata o domande insufficienti
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/questions/validate:
    post:
      tags: [Questions]
      summary: Valida le risposte
      description: Confronta le risposte inviate con quelle attese e calcola l'esito.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateRequest'
            example:
              language: it
              answers:
                4328-21810: true
                1234-5678: false
      responses:
        '200':
          description: Risultato della validazione
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateResponse'
        '400':
          description: Payload non valido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/questions:
    get:
      tags: [Questions]
      summary: Elenco domande
      description: Restituisce fino a 100 domande, opzionalmente filtrate per lingua.
      parameters:
        - name: language
          in: query
          required: false
          schema:
            type: string
            enum: [it, fr, de]
      responses:
        '200':
          description: Elenco domande
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuestionListResponse'

  /images/{filename}:
    get:
      tags: [Images]
      summary: Scarica un'immagine
      parameters:
        - name: filename
          in: path
          required: true
          schema:
            type: string
          example: 4328-it.png
      responses:
        '200':
          description: File immagine
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        '404':
          description: Immagine non trovata

components:
  schemas:
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string

    HealthResponse:
      type: object
      required: [status, questions]
      properties:
        status:
          type: string
          example: ok
        questions:
          type: object
          additionalProperties:
            type: integer
          example:
            it: 1200
            fr: 800
            de: 800

    Question:
      type: object
      required: [id, uuid, quesitoNumber, questionNumber, question, language]
      properties:
        id:
          type: integer
        uuid:
          type: string
          example: 4328-21810
        quesitoNumber:
          type: integer
        questionNumber:
          type: integer
        category:
          type: string
          nullable: true
        question:
          type: string
        language:
          type: string
          enum: [it, fr, de]
        image:
          type: string
          nullable: true
          example: 4328-it.png
        imageUrl:
          type: string
          nullable: true
          example: /images/4328-it.png
        response:
          type: boolean
          description: Presente solo nell'endpoint di elenco domande (admin).

    ExamResponse:
      type: object
      required: [language, count, timeLimitMinutes, maxErrors, questions]
      properties:
        language:
          type: string
          enum: [it, fr, de]
        count:
          type: integer
          example: 30
        timeLimitMinutes:
          type: integer
          example: 20
        maxErrors:
          type: integer
          example: 3
        questions:
          type: array
          items:
            $ref: '#/components/schemas/Question'

    QuestionListResponse:
      type: object
      required: [count, questions]
      properties:
        count:
          type: integer
        questions:
          type: array
          items:
            $ref: '#/components/schemas/Question'

    ValidateRequest:
      type: object
      required: [language, answers]
      properties:
        language:
          type: string
          enum: [it, fr, de]
        answers:
          type: object
          additionalProperties:
            type: boolean
          description: Mappa uuid domanda -> risposta (true = Vero, false = Falso)

    ValidateResultItem:
      type: object
      required: [uuid, correct, expected, given]
      properties:
        uuid:
          type: string
        correct:
          type: boolean
        expected:
          type: boolean
        given:
          type: boolean

    ValidateResponse:
      type: object
      required: [total, errors, maxErrors, passed, results]
      properties:
        total:
          type: integer
        errors:
          type: integer
        maxErrors:
          type: integer
          example: 3
        passed:
          type: boolean
        results:
          type: array
          items:
            $ref: '#/components/schemas/ValidateResultItem'