api-docs.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Mathtexpedia API",
    "description": "Documentación de los endpoints del backend de la Mathtexpedia",
    "version": "v1"
  },
  "servers": [
    { "url": "http://localhost:8081", "description": "Generated server url" }
  ],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    {
      "name": "PDFs públicos",
      "description": "Consulta del catálogo de PDFs sin necesidad de autenticación"
    },
    {
      "name": "Question",
      "description": "Gestión de preguntas; crear/borrar/actualizar requiere rol ADMIN"
    },
    {
      "name": "Usuarios",
      "description": "Búsqueda de usuarios. Requiere rol ADMIN"
    },
    {
      "name": "Asignaturas públicas",
      "description": "Consulta del catálogo de asignaturas y temas sin necesidad de autenticación"
    },
    {
      "name": "Notificaciones",
      "description": "Notificaciones in-app del usuario autenticado (la campanita) y sus preferencias. Requiere JWT; enviar avisos requiere rol ADMIN"
    },
    {
      "name": "Quiz Attempts",
      "description": "Historial de intentos de cuestionarios del usuario autenticado"
    },
    {
      "name": "Cuestionarios públicos",
      "description": "Consulta de cuestionarios sin necesidad de autenticación"
    },
    {
      "name": "Perfil",
      "description": "Perfil de usuario autenticado. Requiere JWT, no requiere rol ADMIN"
    },
    {
      "name": "Option",
      "description": "Gestión de opciones de preguntas; crear/borrar/actualizar requiere rol ADMIN"
    },
    {
      "name": "PDFs",
      "description": "Gestión de PDFs (consulta requiere estar autenticado; crear/borrar/actualizar requiere rol ADMIN)"
    },
    { "name": "Perfil", "description": "Datos del usuario autenticado" },
    {
      "name": "Degrees",
      "description": "Gestión de grados (crear/borrar/actualizar requiere rol ADMIN)"
    },
    {
      "name": "Mail",
      "description": "Envío de correos en nombre del usuario autenticado"
    },
    {
      "name": "Perfil",
      "description": "Fotos de perfil de los usuarios. Requiere JWT, no requiere rol ADMIN"
    },
    {
      "name": "Valoraciones de PDFs",
      "description": "Votos 👍/👎 a los PDFs. Requiere JWT, no requiere rol ADMIN. Solo puede votar quien haya abierto el PDF y no sea su autor; nunca se expone quién votó qué"
    },
    {
      "name": "Subjects",
      "description": "Gestión de asignaturas y temas (crear/borrar/actualizar requiere rol ADMIN; consultar cuestionarios requiere autenticación)"
    },
    {
      "name": "Quiz",
      "description": "Gestión de cuestionarios y preguntas; crear/borrar/actualizar requiere rol ADMIN"
    },
    {
      "name": "Chatbot",
      "description": "Asistente conversacional sobre el contenido de Mathtexpedia"
    },
    {
      "name": "Suscripciones",
      "description": "Asignaturas a las que está suscrito el usuario autenticado. Requiere JWT, no requiere rol ADMIN"
    },
    {
      "name": "Grados públicos",
      "description": "Consulta del catálogo de grados y de sus planes de estudios sin necesidad de autenticación"
    }
  ],
  "paths": {
    "/subject/update/{id}": {
      "put": {
        "tags": ["Subjects"],
        "summary": "Actualiza una asignatura del catálogo",
        "description": "Requiere rol ADMIN. Si 'placements' es nulo no se tocan las colocaciones; si es una lista (también vacía) reemplaza el conjunto completo de colocaciones",
        "operationId": "updateSubject",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la asignatura a actualizar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateSubjectDto" }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Asignatura actualizada",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          },
          "400": {
            "description": "Colocación inválida: grado repetido en la lista o año fuera de los años del grado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          },
          "404": {
            "description": "No existe ninguna asignatura con ese ID o alguna colocación referencia un grado que no existe",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          },
          "401": {
            "description": "El usuario autenticado no tiene rol ADMIN",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          },
          "409": {
            "description": "Ya existe una asignatura con ese nombre",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          }
        }
      }
    },
    "/subject/unit/update/{id}": {
      "put": {
        "tags": ["Subjects"],
        "summary": "Actualiza un tema de una asignatura",
        "description": "Requiere rol ADMIN",
        "operationId": "updateSubjectUnit",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del tema a actualizar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateSubjectUnitDto" }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Tema actualizado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectUnitDto" }
              }
            }
          },
          "404": {
            "description": "No existe ningún tema con ese ID",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectUnitDto" }
              }
            }
          },
          "401": {
            "description": "El usuario autenticado no tiene rol ADMIN",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectUnitDto" }
              }
            }
          },
          "409": {
            "description": "Ya existe un tema con ese nombre para la asignatura",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectUnitDto" }
              }
            }
          }
        }
      }
    },
    "/quiz/update/{id}": {
      "put": {
        "tags": ["Quiz"],
        "summary": "Actualiza un cuestionario por su ID",
        "description": "Requiere rol ADMIN",
        "operationId": "updateQuiz",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario a actualizar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateQuizDto" }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Cuestionario actualizado correctamente",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "400": {
            "description": "Datos de entrada inválidos",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "404": {
            "description": "No existe ningún cuestionario con el ID proporcionado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "409": {
            "description": "Conflicto al actualizar el cuestionario",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          }
        }
      }
    },
    "/question/update/{id}": {
      "put": {
        "tags": ["Question"],
        "summary": "Actualiza una pregunta por su ID",
        "description": "Requiere rol ADMIN",
        "operationId": "updateQuestion",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la pregunta a actualizar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateQuestionDto" }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Pregunta actualizada",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          },
          "400": {
            "description": "Datos de entrada inválidos",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          },
          "404": {
            "description": "Pregunta no encontrada",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          },
          "409": {
            "description": "Conflicto al actualizar la pregunta",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          }
        }
      }
    },
    "/pdf/{pdfId}/rating": {
      "get": {
        "tags": ["Valoraciones de PDFs"],
        "summary": "Valoración de un PDF y mi voto",
        "description": "Resumen público de votos, el voto del usuario autenticado (nulo si no ha votado) y si puede votar ahora. Si no puede, 'cannotVoteReason' indica el motivo: AUTHOR (es autor del PDF) o NOT_VIEWED (todavía no lo ha abierto)",
        "operationId": "getRating",
        "parameters": [
          {
            "name": "pdfId",
            "in": "path",
            "description": "Id del PDF",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Valoración del PDF",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PdfRatingDto" }
              }
            }
          },
          "401": {
            "description": "Sin token válido o cuenta de usuario inactiva",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PdfRatingDto" }
              }
            }
          },
          "404": {
            "description": "No existe ningún PDF con ese id",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PdfRatingDto" }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["Valoraciones de PDFs"],
        "summary": "Voto un PDF o cambio mi voto",
        "description": "Idempotente: votar de nuevo sustituye el voto anterior. Solo puede votar quien haya abierto el PDF (GET /pdf/{pdfId}) al menos una vez y no sea su autor. Devuelve la valoración recalculada",
        "operationId": "rate",
        "parameters": [
          {
            "name": "pdfId",
            "in": "path",
            "description": "Id del PDF",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RatePdfDto" }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Voto guardado; valoración actualizada del PDF",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PdfRatingDto" }
              }
            }
          },
          "400": {
            "description": "Cuerpo inválido (voto ausente o distinto de LIKE/DISLIKE)",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PdfRatingDto" }
              }
            }
          },
          "401": {
            "description": "Sin token válido o cuenta de usuario inactiva",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PdfRatingDto" }
              }
            }
          },
          "403": {
            "description": "El usuario es autor del PDF o todavía no lo ha abierto",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PdfRatingDto" }
              }
            }
          },
          "404": {
            "description": "No existe ningún PDF con ese id",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PdfRatingDto" }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Valoraciones de PDFs"],
        "summary": "Retiro mi voto de un PDF",
        "description": "Idempotente: devuelve 204 también si no había voto. Siempre permitido, incluso si el usuario ya no podría votar",
        "operationId": "removeRating",
        "parameters": [
          {
            "name": "pdfId",
            "in": "path",
            "description": "Id del PDF",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": { "description": "El usuario ya no tiene voto en el PDF" },
          "401": {
            "description": "Sin token válido o cuenta de usuario inactiva"
          },
          "404": { "description": "No existe ningún PDF con ese id" }
        }
      }
    },
    "/pdf/update/{pdfId}": {
      "put": {
        "tags": ["PDFs"],
        "summary": "Actualiza un PDF existente",
        "description": "multipart/form-data con la parte 'data' (JSON) y, opcionalmente, la parte 'file' si se quiere reemplazar el contenido. 'data.authorEmails' sustituye por completo a los autores actuales: el primero es el autor principal (obligatorio) y el resto, coautores (opcionales). Requiere rol ADMIN",
        "operationId": "updatePDF",
        "parameters": [
          {
            "name": "pdfId",
            "in": "path",
            "description": "Id del PDF a actualizar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "data": { "$ref": "#/components/schemas/UpdatePDFDto" },
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Nuevo fichero PDF (opcional)"
                  }
                },
                "required": ["data"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PDF actualizado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/PDFDto" } }
            }
          },
          "400": {
            "description": "Datos inválidos, fichero no válido, lista de autores vacía, emails de autores repetidos o email asociado a más de un usuario",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/PDFDto" } }
            }
          },
          "401": {
            "description": "El usuario autenticado no tiene rol ADMIN",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/PDFDto" } }
            }
          },
          "404": {
            "description": "No existe el PDF, la asignatura, el tema o algún usuario con los emails de autor indicados",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/PDFDto" } }
            }
          },
          "409": {
            "description": "Ya existe un PDF con ese nombre",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/PDFDto" } }
            }
          }
        }
      }
    },
    "/option/update/{id}": {
      "put": {
        "tags": ["Option"],
        "summary": "Actualiza una opción por su ID",
        "description": "Requiere rol ADMIN",
        "operationId": "updateOption",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la opción a actualizar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateOptionDto" }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Opción actualizada correctamente",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          },
          "400": {
            "description": "Datos de entrada inválidos",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          },
          "404": {
            "description": "No existe ninguna opción con el ID proporcionado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          },
          "409": {
            "description": "Conflicto al actualizar la opción",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          }
        }
      }
    },
    "/notifications/preferences": {
      "get": {
        "tags": ["Notificaciones"],
        "summary": "Mis preferencias de notificación",
        "description": "Matriz completa de tipos configurables por canal, con los valores por defecto donde el usuario no ha elegido. Los tipos no configurables (bienvenida, avisos) no aparecen porque se entregan siempre",
        "operationId": "getMyPreferences",
        "responses": {
          "200": {
            "description": "Preferencias del usuario",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NotificationPreferenceDto"
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado o cuenta inactiva",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NotificationPreferenceDto"
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["Notificaciones"],
        "summary": "Actualiza mis preferencias de notificación",
        "description": "Cambio parcial: solo se modifican las preferencias indicadas. Devuelve la matriz completa actualizada",
        "operationId": "updateMyPreferences",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateNotificationPreferencesDto"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Matriz completa de preferencias",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NotificationPreferenceDto"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Datos inválidos, tipo no configurable o alcance no admitido por el tipo",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NotificationPreferenceDto"
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado o cuenta inactiva",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NotificationPreferenceDto"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/me": {
      "get": {
        "tags": ["Perfil"],
        "summary": "Perfil del usuario autenticado",
        "description": "Si es el primer acceso del usuario, crea su perfil a partir del JWT",
        "operationId": "getMe",
        "responses": {
          "200": {
            "description": "Perfil del usuario obtenido",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["Perfil"],
        "summary": "Actualiza el perfil del usuario autenticado",
        "description": "Sustituye todos los datos del perfil: el username es obligatorio y los demás campos, opcionales; uno que no se envíe (o venga en blanco) se borra. El primer guardado marca el perfil como completado. El grado y el curso (degreeId, currentYear) siguen la misma regla: nulos se borran. No toca la foto de perfil",
        "operationId": "updateMe",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateUserAccountDto" }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Perfil actualizado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          },
          "400": {
            "description": "Datos de entrada inválidos (username vacío o con formato incorrecto, campos demasiado largos, currentYear sin degreeId o mayor que los años del grado)",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          },
          "404": {
            "description": "El grado indicado en degreeId no existe",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          },
          "409": {
            "description": "El username ya lo usa otro usuario (sin distinguir mayúsculas)",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          }
        }
      }
    },
    "/me/subscriptions/{subjectId}": {
      "put": {
        "tags": ["Suscripciones"],
        "summary": "Me suscribo a una asignatura",
        "description": "Idempotente: si ya estaba suscrito devuelve la suscripción existente con 200",
        "operationId": "subscribe",
        "parameters": [
          {
            "name": "subjectId",
            "in": "path",
            "description": "ID de la asignatura",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Suscripción activa",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/SubjectSubscriptionDto"
                }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/SubjectSubscriptionDto"
                }
              }
            }
          },
          "404": {
            "description": "No existe ninguna asignatura con ese ID",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/SubjectSubscriptionDto"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Suscripciones"],
        "summary": "Me doy de baja de una asignatura",
        "description": "Idempotente: devuelve 204 también si no estaba suscrito",
        "operationId": "unsubscribe",
        "parameters": [
          {
            "name": "subjectId",
            "in": "path",
            "description": "ID de la asignatura",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": {
            "description": "El usuario ya no está suscrito a la asignatura"
          },
          "401": { "description": "No autenticado" }
        }
      }
    },
    "/me/subscriptions/degree/{degreeId}/year/{year}": {
      "put": {
        "tags": ["Suscripciones"],
        "summary": "Me suscribo a un curso entero",
        "description": "Suscribe a todas las asignaturas colocadas ahora en ese grado y año (y cuatrimestre, si se indica). Es una foto fija: las asignaturas que se coloquen después no se suscriben solas. Idempotente: las que ya estaban suscritas se conservan. Devuelve las suscripciones a las asignaturas de ese curso, ordenadas por nombre",
        "operationId": "subscribeToCourse",
        "parameters": [
          {
            "name": "degreeId",
            "in": "path",
            "description": "ID del grado",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "year",
            "in": "path",
            "description": "Año (curso) del grado, de 1 a sus años",
            "required": true,
            "schema": { "type": "integer", "format": "int32" }
          },
          {
            "name": "semester",
            "in": "query",
            "description": "Cuatrimestre (1 o 2). Si se omite, incluye las asignaturas de cualquier cuatrimestre y las anuales",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "200": {
            "description": "Suscripciones del usuario a las asignaturas del curso (vacía si el curso no tiene asignaturas)",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SubjectSubscriptionDto"
                  }
                }
              }
            }
          },
          "400": {
            "description": "El año está fuera de 1..años del grado o el cuatrimestre no es 1 ni 2",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SubjectSubscriptionDto"
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SubjectSubscriptionDto"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No existe ningún grado con ese ID",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SubjectSubscriptionDto"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Suscripciones"],
        "summary": "Me doy de baja de un curso entero",
        "description": "Da de baja de todas las asignaturas colocadas ahora en ese grado y año (y cuatrimestre, si se indica), también de las que estén colocadas además en otro curso al que el usuario siga suscrito. Idempotente: devuelve 204 también si no había ninguna suscripción",
        "operationId": "unsubscribeFromCourse",
        "parameters": [
          {
            "name": "degreeId",
            "in": "path",
            "description": "ID del grado",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "year",
            "in": "path",
            "description": "Año (curso) del grado, de 1 a sus años",
            "required": true,
            "schema": { "type": "integer", "format": "int32" }
          },
          {
            "name": "semester",
            "in": "query",
            "description": "Cuatrimestre (1 o 2). Si se omite, incluye las asignaturas de cualquier cuatrimestre y las anuales",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "204": {
            "description": "El usuario ya no está suscrito a las asignaturas del curso"
          },
          "400": {
            "description": "El año está fuera de 1..años del grado o el cuatrimestre no es 1 ni 2"
          },
          "401": { "description": "No autenticado" },
          "404": { "description": "No existe ningún grado con ese ID" }
        }
      }
    },
    "/me/avatar": {
      "put": {
        "tags": ["Perfil"],
        "summary": "Sube o cambia mi foto de perfil",
        "description": "multipart/form-data con la parte 'file': imagen JPEG o PNG de hasta 2 MB y al menos 64x64 píxeles. Se recorta a cuadrado, se reduce a 256 px como máximo y se guarda como JPEG; la imagen original no se conserva. Sustituye a la anterior. Devuelve el perfil actualizado (con hasAvatar y avatarUpdatedAt)",
        "operationId": "updateAvatar",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Imagen JPEG o PNG"
                  }
                },
                "required": ["file"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Foto guardada",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          },
          "400": {
            "description": "Falta el fichero, no es JPEG/PNG, está corrupto, pesa más de 2 MB o no cumple el tamaño mínimo/máximo en píxeles",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          },
          "413": {
            "description": "La petición supera el límite de subida del servidor",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Perfil"],
        "summary": "Elimina mi foto de perfil",
        "description": "Idempotente: si no tenía foto no hace nada. Devuelve el perfil actualizado",
        "operationId": "deleteAvatar",
        "responses": {
          "200": {
            "description": "Foto eliminada (o no existía)",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserAccountDto" }
              }
            }
          }
        }
      }
    },
    "/degree/update/{id}": {
      "put": {
        "tags": ["Degrees"],
        "summary": "Actualiza un grado del catálogo",
        "description": "Requiere rol ADMIN. Reemplaza todos los campos. Si reduce los años, los usuarios con un curso mayor en su perfil lo pierden",
        "operationId": "updateDegree",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del grado a actualizar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateDegreeDto" }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Grado actualizado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/DegreeDto" } }
            }
          },
          "404": {
            "description": "No existe ningún grado con ese ID",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/DegreeDto" } }
            }
          },
          "401": {
            "description": "El usuario autenticado no tiene rol ADMIN",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/DegreeDto" } }
            }
          },
          "409": {
            "description": "Ya existe un grado con ese nombre y universidad, o hay asignaturas colocadas en los años que desaparecerían",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/DegreeDto" } }
            }
          }
        }
      }
    },
    "/subject/{subjectId}/unit/create": {
      "post": {
        "tags": ["Subjects"],
        "summary": "Crea un nuevo tema para una asignatura",
        "description": "Requiere rol ADMIN",
        "operationId": "createSubjectUnit",
        "parameters": [
          {
            "name": "subjectId",
            "in": "path",
            "description": "ID de la asignatura a la que pertenece el tema",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateSubjectUnitDto" }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Tema creado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectUnitDto" }
              }
            }
          },
          "404": {
            "description": "No existe ninguna asignatura con ese ID",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectUnitDto" }
              }
            }
          },
          "409": {
            "description": "Ya existe un tema con ese nombre para la asignatura",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectUnitDto" }
              }
            }
          },
          "401": {
            "description": "El usuario autenticado no tiene rol ADMIN",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectUnitDto" }
              }
            }
          }
        }
      }
    },
    "/subject/create": {
      "post": {
        "tags": ["Subjects"],
        "summary": "Crea una nueva asignatura en el catálogo",
        "description": "Requiere rol ADMIN. Opcionalmente la coloca en grados con 'placements' (sin colocaciones si es nulo o vacío)",
        "operationId": "createSubject",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateSubjectDto" }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Asignatura creada",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          },
          "400": {
            "description": "Colocación inválida: grado repetido en la lista o año fuera de los años del grado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          },
          "404": {
            "description": "Alguna colocación referencia un grado que no existe",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          },
          "409": {
            "description": "Ya existe una asignatura con ese nombre",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          },
          "401": {
            "description": "El usuario autenticado no tiene rol ADMIN",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          }
        }
      }
    },
    "/quiz/{id}/submit": {
      "post": {
        "tags": ["Quiz"],
        "summary": "Envía un intento de cuestionario para su evaluación",
        "description": "Requiere autenticación, pero no requiere rol ADMIN",
        "operationId": "submitAttempt",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario a enviar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SubmitQuizAttemptDto" }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Intento de cuestionario evaluado correctamente",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/QuizAttemptResultDto"
                }
              }
            }
          },
          "400": {
            "description": "Datos de entrada inválidos",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/QuizAttemptResultDto"
                }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/QuizAttemptResultDto"
                }
              }
            }
          },
          "404": {
            "description": "No existe ningún cuestionario con el ID proporcionado",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/QuizAttemptResultDto"
                }
              }
            }
          }
        }
      }
    },
    "/quiz/{id}/questions/import": {
      "post": {
        "tags": ["Quiz"],
        "summary": "Añade preguntas desde JSON al final de un cuestionario existente",
        "description": "Usa el mismo formato de pregunta que el export/import de cuestionarios. Se añaden todas o ninguna. Se ignoran las position del JSON: las preguntas nuevas van a continuación de la última (max(position) + 1 en adelante, o 1..n si el cuestionario está vacío) en el orden de la lista, y las opciones de cada pregunta se numeran 1..m. Se aplica la misma validación que al importar un cuestionario. No cambia la visibilidad del cuestionario ni notifica a nadie. Requiere rol ADMIN",
        "operationId": "importQuestions",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario al que se añaden las preguntas",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ImportQuestionsDto" }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Preguntas creadas, en el orden de la lista",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuestionDto" }
                }
              }
            }
          },
          "400": {
            "description": "Datos de entrada inválidos (p. ej. una pregunta sin exactamente una opción correcta)",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuestionDto" }
                }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuestionDto" }
                }
              }
            }
          },
          "404": {
            "description": "No existe ningún cuestionario con el ID proporcionado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuestionDto" }
                }
              }
            }
          }
        }
      }
    },
    "/quiz/import": {
      "post": {
        "tags": ["Quiz"],
        "summary": "Importa un cuestionario completo desde JSON",
        "description": "El JSON no incluye asignatura ni tema; se seleccionan aparte al importar. Con publish = true (por defecto) se publica al momento (visible) y se notifica a los usuarios. Con publish = false se queda OCULTO, como al crearlo con POST /quiz/create, sin notificar a nadie; se publica después con PATCH /quiz/{id}/visibility. Se ignoran las position del JSON: las preguntas se numeran 1..n en el orden de la lista, y las opciones de cada pregunta, 1..m. Cada pregunta MULTIPLE_CHOICE debe tener al menos 2 opciones y cada TRUE_FALSE exactamente 2, en ambos casos con exactamente una correcta. Una explanation vacía se guarda como null. Requiere rol ADMIN",
        "operationId": "importQuiz",
        "parameters": [
          {
            "name": "subjectId",
            "in": "query",
            "description": "ID de la asignatura a la que se asocia el cuestionario importado",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "subjectUnitId",
            "in": "query",
            "description": "ID del tema al que se asocia el cuestionario importado",
            "required": false,
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "publish",
            "in": "query",
            "description": "true (por defecto) para publicarlo al momento y notificar a los usuarios; false para dejarlo oculto y publicarlo después con PATCH /quiz/{id}/visibility",
            "required": false,
            "schema": { "type": "boolean", "default": true }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/QuizExportableDto" }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Cuestionario importado correctamente",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "400": {
            "description": "Datos de entrada inválidos (p. ej. una pregunta sin exactamente una opción correcta o una descripción de más de 500 caracteres)",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "404": {
            "description": "No existe ninguna asignatura o unidad de asignatura con el ID proporcionado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "409": {
            "description": "Conflicto al crear el cuestionario",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          }
        }
      }
    },
    "/quiz/create": {
      "post": {
        "tags": ["Quiz"],
        "summary": "Crea un nuevo cuestionario",
        "description": "Se crea OCULTO (visible = false), porque se rellena pregunta a pregunta. Para publicarlo hay que usar PATCH /quiz/{id}/visibility. Requiere rol ADMIN",
        "operationId": "createQuiz",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateQuizDto" }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Cuestionario creado correctamente",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "400": {
            "description": "Datos de entrada inválidos",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "404": {
            "description": "No existe ninguna asignatura o unidad de asignatura con el ID proporcionado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "409": {
            "description": "Conflicto al crear el cuestionario",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          }
        }
      }
    },
    "/question/create": {
      "post": {
        "tags": ["Question"],
        "summary": "Crea una nueva pregunta",
        "description": "Requiere rol ADMIN",
        "operationId": "createQuestion",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateQuestionDto" }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Pregunta creada",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          },
          "404": {
            "description": "No existe el cuestionario a la que se quiere asociar la pregunta",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          },
          "409": {
            "description": "Conflicto al crear la pregunta",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          }
        }
      }
    },
    "/pdf/create": {
      "post": {
        "tags": ["PDFs"],
        "summary": "Crea un nuevo PDF en el catálogo",
        "description": "multipart/form-data con la parte 'data' (JSON) y la parte 'file' (PDF). En 'data.authorEmails' se indican los emails de los autores: el primero es el autor principal (obligatorio) y el resto, coautores (opcionales). Requiere rol ADMIN",
        "operationId": "createPDF",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "data": { "$ref": "#/components/schemas/CreatePDFDto" },
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Fichero PDF"
                  }
                },
                "required": ["data", "file"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "PDF creado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/PDFDto" } }
            }
          },
          "400": {
            "description": "Datos inválidos, fichero no válido, lista de autores vacía, emails de autores repetidos o email asociado a más de un usuario",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/PDFDto" } }
            }
          },
          "401": {
            "description": "El usuario autenticado no tiene rol ADMIN",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/PDFDto" } }
            }
          },
          "404": {
            "description": "No existe la asignatura, el tema o algún usuario con los emails de autor indicados",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/PDFDto" } }
            }
          },
          "409": {
            "description": "Ya existe un PDF con ese nombre",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/PDFDto" } }
            }
          }
        }
      }
    },
    "/option/create": {
      "post": {
        "tags": ["Option"],
        "summary": "Crea una nueva opción",
        "description": "Requiere rol ADMIN",
        "operationId": "createOption",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateOptionDto" }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Opción creada",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          },
          "400": {
            "description": "Datos de entrada inválidos",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          },
          "404": {
            "description": "Pregunta no encontrada",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          },
          "409": {
            "description": "Conflicto al crear la opción",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          }
        }
      }
    },
    "/notifications/announcements": {
      "post": {
        "tags": ["Notificaciones"],
        "summary": "Envía un aviso a los usuarios",
        "description": "A todos los usuarios activos o solo a los indicados por email. El reparto es asíncrono. El enlace opcional debe ser una ruta interna que empiece por '/'. Requiere rol ADMIN",
        "operationId": "createAnnouncement",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateAnnouncementDto" }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Aviso aceptado; se reparte en segundo plano"
          },
          "400": { "description": "Datos inválidos o enlace no interno" },
          "401": { "description": "El usuario autenticado no tiene rol ADMIN" },
          "404": {
            "description": "Algún email no corresponde a ningún usuario"
          }
        }
      }
    },
    "/mail/send": {
      "post": {
        "tags": ["Mail"],
        "summary": "Envía un correo",
        "description": "El remitente se rellena a partir del usuario autenticado si no se indica en el body",
        "operationId": "sendMain",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Mail" }
            }
          },
          "required": true
        },
        "responses": {
          "200": { "description": "Correo enviado correctamente" },
          "500": {
            "description": "El proveedor de correo no pudo procesar el envío"
          }
        }
      }
    },
    "/degree/create": {
      "post": {
        "tags": ["Degrees"],
        "summary": "Crea un nuevo grado en el catálogo",
        "description": "Requiere rol ADMIN",
        "operationId": "createDegree",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateDegreeDto" }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Grado creado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/DegreeDto" } }
            }
          },
          "409": {
            "description": "Ya existe un grado con ese nombre y universidad",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/DegreeDto" } }
            }
          },
          "401": {
            "description": "El usuario autenticado no tiene rol ADMIN",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/DegreeDto" } }
            }
          }
        }
      }
    },
    "/chatbot/chat": {
      "post": {
        "tags": ["Chatbot"],
        "summary": "Envía un mensaje al chatbot",
        "description": "Acepta tanto peticiones anónimas como autenticadas; si se envía un JWT válido, la respuesta puede tener en cuenta el contexto del usuario",
        "operationId": "chat",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatRequest" }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/ChatResponse" }
              }
            }
          }
        }
      }
    },
    "/quiz/{id}/visibility": {
      "patch": {
        "tags": ["Quiz"],
        "summary": "Publica u oculta un cuestionario",
        "description": "Los cuestionarios ocultos solo los ve un administrador. Publicar uno sin preguntas es un error (400). La primera vez que se publica se notifica a los usuarios; ocultarlo y publicarlo de nuevo no vuelve a notificar. Requiere rol ADMIN",
        "operationId": "updateQuizVisibility",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateQuizVisibilityDto"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Visibilidad actualizada (también si ya estaba en ese estado)",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "400": {
            "description": "Datos de entrada inválidos o el cuestionario no tiene preguntas",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          },
          "404": {
            "description": "No existe ningún cuestionario con el ID proporcionado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          }
        }
      }
    },
    "/notifications/{id}/unread": {
      "patch": {
        "tags": ["Notificaciones"],
        "summary": "Marca una notificación como no leída",
        "operationId": "markAsUnread",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Id de la notificación",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": { "description": "Marcada como no leída" },
          "401": { "description": "No autenticado" },
          "404": { "description": "No existe o no es del usuario" }
        }
      }
    },
    "/notifications/{id}/read": {
      "patch": {
        "tags": ["Notificaciones"],
        "summary": "Marca una notificación como leída",
        "description": "Idempotente: si ya estaba leída no es un error",
        "operationId": "markAsRead",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Id de la notificación",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": { "description": "Marcada como leída" },
          "401": { "description": "No autenticado" },
          "404": { "description": "No existe o no es del usuario" }
        }
      }
    },
    "/notifications/read-all": {
      "patch": {
        "tags": ["Notificaciones"],
        "summary": "Marca todas las notificaciones como leídas",
        "operationId": "markAllAsRead",
        "responses": {
          "200": {
            "description": "Número de notificaciones marcadas",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/MarkAllReadResultDto"
                }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/MarkAllReadResultDto"
                }
              }
            }
          }
        }
      }
    },
    "/users/{userId}/avatar": {
      "get": {
        "tags": ["Perfil"],
        "summary": "Foto de perfil de un usuario",
        "description": "Imagen JPEG cuadrada de hasta 256 px. Solo para usuarios autenticados: al llevar el token en cabecera no sirve como 'src' directo de una etiqueta img, hay que pedirla con fetch y mostrarla como blob. Admite If-None-Match (ETag derivado de avatarUpdatedAt): responde 304 sin cuerpo si no ha cambiado",
        "operationId": "getAvatar",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "description": "Identificador interno del usuario",
            "required": true,
            "schema": { "type": "integer", "format": "int64" },
            "example": 42
          }
        ],
        "responses": {
          "200": {
            "description": "Imagen JPEG",
            "content": { "image/jpeg": {} }
          },
          "304": {
            "description": "La foto no ha cambiado desde la versión indicada en If-None-Match",
            "content": {
              "image/jpeg": { "schema": { "type": "string", "format": "byte" } }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "image/jpeg": { "schema": { "type": "string", "format": "byte" } }
            }
          },
          "404": {
            "description": "El usuario no existe, está inactivo o no tiene foto",
            "content": {
              "image/jpeg": { "schema": { "type": "string", "format": "byte" } }
            }
          }
        }
      }
    },
    "/users/search": {
      "get": {
        "tags": ["Usuarios"],
        "summary": "Busca usuarios que pueden ser autores o coautores de un PDF",
        "description": "Devuelve los usuarios activos cuyo nombre o email contiene el texto buscado (sin distinguir mayúsculas ni tildes), ordenados por nombre (o por email si no tienen nombre). Pensado para un buscador con sugerencias: el front debe aplicar debounce y cancelar la petición anterior. Si 'q' tiene menos de 2 caracteres (tras quitar espacios) devuelve una lista vacía. Requiere rol ADMIN",
        "operationId": "searchUsers",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Texto a buscar en nombre o email (mínimo 2 caracteres)",
            "required": false,
            "schema": { "type": "string" },
            "example": "ada"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Máximo de resultados (por defecto 10, máximo 20)",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de candidatos (puede estar vacía)",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/AuthorCandidateDto" }
                }
              }
            }
          },
          "401": {
            "description": "Sin token válido o el usuario autenticado no tiene rol ADMIN",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/AuthorCandidateDto" }
                }
              }
            }
          }
        }
      }
    },
    "/subject/{id}/quizzes": {
      "get": {
        "tags": ["Subjects"],
        "summary": "Obtiene todos los cuestionarios de una asignatura",
        "description": "Requiere autenticación, pero no requiere rol ADMIN. Los cuestionarios ocultos solo se incluyen para administradores",
        "operationId": "getSubjectQuizzes",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la asignatura",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de cuestionarios obtenida",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          },
          "404": {
            "description": "No existe ninguna asignatura con ese ID",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          }
        }
      }
    },
    "/subject/unit/{id}/quizzes": {
      "get": {
        "tags": ["Subjects"],
        "summary": "Obtiene todos los cuestionarios de un tema",
        "description": "Requiere autenticación, pero no requiere rol ADMIN. Los cuestionarios ocultos solo se incluyen para administradores",
        "operationId": "getSubjectUnitQuizzes",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del tema",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de cuestionarios obtenida",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          },
          "404": {
            "description": "No existe ningún tema con ese ID",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          }
        }
      }
    },
    "/quiz": {
      "get": {
        "tags": ["Quiz"],
        "summary": "Lista todos los cuestionarios",
        "description": "Requiere autenticación, pero no requiere rol ADMIN. Para un administrador incluye también los cuestionarios ocultos (es lo que necesita el panel de administración para poder publicarlos); para el resto, solo los visibles. El listado público GET /public/quiz nunca incluye los ocultos",
        "operationId": "getAllQuizzes",
        "responses": {
          "200": {
            "description": "Lista de cuestionarios con el número de intentos de cada uno",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          }
        }
      }
    },
    "/quiz/{id}": {
      "get": {
        "tags": ["Quiz"],
        "summary": "Obtiene un cuestionario por su ID",
        "description": "Requiere autenticación, pero no requiere rol ADMIN. Si el cuestionario está oculto, solo lo ve un administrador (404 para el resto)",
        "operationId": "getQuiz",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/QuizDto" } }
            }
          }
        }
      }
    },
    "/quiz/{id}/stats": {
      "get": {
        "tags": ["Quiz"],
        "summary": "Obtiene mis estadísticas de un cuestionario",
        "description": "Estadísticas agregadas de los intentos del usuario autenticado en este cuestionario (totalAttempts, bestScore sobre 10, etc.). Si totalAttempts es 0 el usuario aún no lo ha intentado y el resto de valores son 0. Requiere autenticación, pero no requiere rol ADMIN",
        "operationId": "getUserStatsForQuiz",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Estadísticas de cuestionario obtenidas correctamente",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuizAttemptStatsDto" }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuizAttemptStatsDto" }
              }
            }
          },
          "404": {
            "description": "No existe ningún cuestionario con el ID proporcionado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuizAttemptStatsDto" }
              }
            }
          }
        }
      }
    },
    "/quiz/{id}/questions": {
      "get": {
        "tags": ["Quiz"],
        "summary": "Obtiene las preguntas de un cuestionario por su ID",
        "description": "Incluye la explicación de la respuesta correcta, por lo que es solo para edición. Para resolver el cuestionario usar GET /quiz/{id}/attempt. Requiere rol ADMIN",
        "operationId": "getQuizQuestions",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Preguntas obtenidas correctamente",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuestionDto" }
                }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuestionDto" }
                }
              }
            }
          },
          "404": {
            "description": "No existe ningún cuestionario con el ID proporcionado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuestionDto" }
                }
              }
            }
          }
        }
      }
    },
    "/quiz/{id}/leaderboard": {
      "get": {
        "tags": ["Quiz"],
        "summary": "Obtiene la tabla de líderes de un cuestionario por su ID",
        "description": "Requiere autenticación, pero no requiere rol ADMIN",
        "operationId": "getLeaderboardForQuiz",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "pageable",
            "in": "query",
            "description": "Parámetros de paginación",
            "required": true,
            "schema": { "$ref": "#/components/schemas/Pageable" }
          }
        ],
        "responses": {
          "200": {
            "description": "Tabla de líderes obtenida correctamente",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/PageLeaderboardEntryDto"
                }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/PageLeaderboardEntryDto"
                }
              }
            }
          },
          "404": {
            "description": "No existe ningún cuestionario con el ID proporcionado",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/PageLeaderboardEntryDto"
                }
              }
            }
          }
        }
      }
    },
    "/quiz/{id}/export": {
      "get": {
        "tags": ["Quiz"],
        "summary": "Exporta un cuestionario completo a JSON",
        "description": "Requiere rol ADMIN",
        "operationId": "exportQuiz",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario a exportar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Cuestionario exportado correctamente",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuizExportableDto" }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuizExportableDto" }
              }
            }
          },
          "404": {
            "description": "No existe ningún cuestionario con el ID proporcionado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuizExportableDto" }
              }
            }
          }
        }
      }
    },
    "/quiz/{id}/attempts": {
      "get": {
        "tags": ["Quiz"],
        "summary": "Obtiene mis intentos de un cuestionario",
        "description": "Devuelve únicamente los intentos del usuario autenticado en este cuestionario, ordenados del más reciente al más antiguo; nunca los de otros usuarios. Para mostrar solo la mejor puntuación o saber si ya lo ha intentado, usar GET /quiz/{id}/stats. Requiere autenticación, pero no requiere rol ADMIN",
        "operationId": "getAttemptsForQuiz",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Intentos de cuestionario obtenidos correctamente",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizAttemptDto" }
                }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizAttemptDto" }
                }
              }
            }
          },
          "404": {
            "description": "No existe ningún cuestionario con el ID proporcionado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizAttemptDto" }
                }
              }
            }
          }
        }
      }
    },
    "/quiz/{id}/attempt": {
      "get": {
        "tags": ["Quiz"],
        "summary": "Obtiene un cuestionario por su ID para intentar resolverlo",
        "description": "Requiere autenticación, pero no requiere rol ADMIN. Si el cuestionario está oculto, solo lo ve un administrador (404 para el resto)",
        "operationId": "getQuizForAttempt",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Cuestionario obtenido correctamente",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuizForAttemptDto" }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuizForAttemptDto" }
              }
            }
          },
          "404": {
            "description": "No existe ningún cuestionario con el ID proporcionado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuizForAttemptDto" }
              }
            }
          }
        }
      }
    },
    "/quiz/recent/subscribed": {
      "get": {
        "tags": ["Quiz"],
        "summary": "Cuestionarios nuevos o actualizados de las asignaturas a las que estoy suscrito",
        "description": "Como GET /public/quiz/recent pero solo de las asignaturas suscritas, del más reciente al más antiguo. Lista vacía si el usuario no tiene suscripciones. Los ocultos solo se incluyen para administradores",
        "operationId": "getRecentSubscribedQuizzes",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Máximo de cuestionarios a devolver (por defecto 10, máximo 20)",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de cuestionarios (puede estar vacía)",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          }
        }
      }
    },
    "/question/{id}": {
      "get": {
        "tags": ["Question"],
        "summary": "Obtiene una pregunta por su ID",
        "description": "Incluye la explicación de la respuesta correcta, por lo que es solo para edición. Requiere rol ADMIN",
        "operationId": "getQuestion",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la pregunta",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Pregunta encontrada",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          },
          "404": {
            "description": "Pregunta no encontrada",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuestionDto" }
              }
            }
          }
        }
      }
    },
    "/question/{id}/options": {
      "get": {
        "tags": ["Question"],
        "summary": "Obtiene las opciones de una pregunta por su ID",
        "description": "Incluye cuál es la opción correcta, por lo que es solo para edición. Para resolver un cuestionario usar GET /quiz/{id}/attempt. Requiere rol ADMIN",
        "operationId": "getQuestionOptions",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la pregunta",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Pregunta encontrada",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/OptionDto" }
                }
              }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/OptionDto" }
                }
              }
            }
          },
          "404": {
            "description": "Pregunta no encontrada",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/OptionDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/subject": {
      "get": {
        "tags": ["Asignaturas públicas"],
        "summary": "Lista las asignaturas con sus colocaciones en grados",
        "description": "Ordenadas por nombre. Sin filtros devuelve todas. 'year' y 'semester' exigen 'degreeId' (también 'semester' sin 'year'). 'unassigned=true' lista las asignaturas que no están colocadas en ningún grado y no se puede combinar con 'degreeId'",
        "operationId": "getSubjects",
        "parameters": [
          {
            "name": "degreeId",
            "in": "query",
            "description": "Solo las asignaturas colocadas en este grado",
            "required": false,
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "year",
            "in": "query",
            "description": "Solo las colocadas en este año del grado (requiere degreeId)",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          },
          {
            "name": "semester",
            "in": "query",
            "description": "Solo las colocadas en este cuatrimestre, 1 o 2 (requiere degreeId)",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          },
          {
            "name": "unassigned",
            "in": "query",
            "description": "Solo las asignaturas sin colocación en ningún grado (no combinable con degreeId)",
            "required": false,
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de asignaturas obtenida (puede estar vacía)",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/SubjectDetailDto" }
                }
              }
            }
          },
          "400": {
            "description": "Combinación de filtros inválida o 'year'/'semester' fuera de rango",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/SubjectDetailDto" }
                }
              }
            }
          },
          "404": {
            "description": "No existe ningún grado con ese 'degreeId'",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/SubjectDetailDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/subject/{id}": {
      "get": {
        "tags": ["Asignaturas públicas"],
        "summary": "Obtiene una asignatura por su ID, con sus colocaciones en grados",
        "operationId": "getSubject",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la asignatura",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Asignatura obtenida",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          },
          "404": {
            "description": "No existe ninguna asignatura con ese ID",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectDetailDto" }
              }
            }
          }
        }
      }
    },
    "/public/subject/{id}/units": {
      "get": {
        "tags": ["Asignaturas públicas"],
        "summary": "Obtiene los temas de una asignatura",
        "operationId": "getSubjectUnits",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la asignatura",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de temas obtenida",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/SubjectUnitDto" }
                }
              }
            }
          },
          "404": {
            "description": "No existe ninguna asignatura con ese ID",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/SubjectUnitDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/subject/{id}/pdfs": {
      "get": {
        "tags": ["Asignaturas públicas"],
        "summary": "Obtiene todos los pdfs de una asignatura",
        "operationId": "getSubjectPDFs",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la asignatura",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Orden del listado: RATING (mejor valorados primero), VIEWS (más vistos), RECENT (editados más recientemente) o NAME (alfabético sin distinguir mayúsculas ni acentos). Si se omite, orden por defecto",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["RATING", "VIEWS", "RECENT", "NAME"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de pdfs obtenida",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PDFDto" }
                }
              }
            }
          },
          "400": {
            "description": "Valor de 'sort' no válido",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PDFDto" }
                }
              }
            }
          },
          "404": {
            "description": "No existe ninguna asignatura con ese ID",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PDFDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/subject/unit/{id}": {
      "get": {
        "tags": ["Asignaturas públicas"],
        "summary": "Obtiene un tema de una asignatura por su ID",
        "operationId": "getSubjectUnit",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del tema",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SubjectUnitDto" }
              }
            }
          }
        }
      }
    },
    "/public/quiz": {
      "get": {
        "tags": ["Cuestionarios públicos"],
        "summary": "Lista todos los cuestionarios",
        "description": "Incluye el número de intentos (attemptCount) de cada cuestionario",
        "operationId": "getAllQuizzes_1",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/quiz/top": {
      "get": {
        "tags": ["Cuestionarios públicos"],
        "summary": "Cuestionarios más hechos en general",
        "description": "Ordenados de más a menos intentos contando los envíos de todos los usuarios. Solo incluye cuestionarios con al menos un intento. Pensado para la hilera 'Los más hechos'",
        "operationId": "getMostAttemptedQuizzes",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Máximo de cuestionarios a devolver (por defecto 10, máximo 20)",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/quiz/recent": {
      "get": {
        "tags": ["Cuestionarios públicos"],
        "summary": "Cuestionarios nuevos o actualizados recientemente",
        "description": "Del más reciente al más antiguo según la fecha de última edición. Pensado para la hilera 'Novedades'",
        "operationId": "getRecentQuizzes",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Máximo de cuestionarios a devolver (por defecto 10, máximo 20)",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuizDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/pdf/top": {
      "get": {
        "tags": ["PDFs públicos"],
        "summary": "PDFs más vistos en general",
        "description": "Ordenados de más a menos vistas contando todas las aperturas de todos los usuarios. Solo incluye PDFs con al menos una vista. Pensado para la hilera 'Lo más visto' del feed",
        "operationId": "getTopViewedPDFs",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Máximo de PDFs a devolver (por defecto 10, máximo 20)",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PDFDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/pdf/top-rated": {
      "get": {
        "tags": ["PDFs públicos"],
        "summary": "PDFs mejor valorados",
        "description": "Solo PDFs con al menos 3 votos y más 👍 que 👎, ordenados por puntuación ('rating.score', límite inferior de Wilson) de mayor a menor. Pensado para la hilera 'Mejor valorados' del feed; lista vacía si ninguno cumple",
        "operationId": "getTopRatedPDFs",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Máximo de PDFs a devolver (por defecto 10, máximo 20)",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PDFDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/pdf/recent": {
      "get": {
        "tags": ["PDFs públicos"],
        "summary": "PDFs nuevos o actualizados recientemente",
        "description": "Del más reciente al más antiguo según la fecha de última edición. Pensado para la hilera 'Novedades' del feed",
        "operationId": "getRecentPDFs",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Máximo de PDFs a devolver (por defecto 10, máximo 20)",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PDFDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/pdf/no-link": {
      "get": {
        "tags": ["PDFs públicos"],
        "summary": "Lista el catálogo de PDFs",
        "description": "Solo metadatos (incluidos el nombre del autor, los de los coautores y el número de vistas); el contenido se obtiene autenticado en GET /pdf/{pdfId}/content. Cada PDF incluye el resumen público de valoraciones ('rating'). Sin 'sort' se devuelve en el orden por defecto",
        "operationId": "getPDFs",
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "description": "Orden del listado: RATING (mejor valorados primero), VIEWS (más vistos), RECENT (editados más recientemente) o NAME (alfabético sin distinguir mayúsculas ni acentos). Si se omite, orden por defecto",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["RATING", "VIEWS", "RECENT", "NAME"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PDFDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/degree": {
      "get": {
        "tags": ["Grados públicos"],
        "summary": "Lista todos los grados",
        "description": "Ordenados por nombre y universidad",
        "operationId": "getDegrees",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/DegreeDto" }
                }
              }
            }
          }
        }
      }
    },
    "/public/degree/{id}": {
      "get": {
        "tags": ["Grados públicos"],
        "summary": "Obtiene un grado por su ID",
        "operationId": "getDegree",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del grado",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Grado obtenido",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/DegreeDto" } }
            }
          },
          "404": {
            "description": "No existe ningún grado con ese ID",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/DegreeDto" } }
            }
          }
        }
      }
    },
    "/public/degree/{id}/curriculum": {
      "get": {
        "tags": ["Grados públicos"],
        "summary": "Obtiene el plan de estudios de un grado",
        "description": "Asignaturas colocadas en el grado agrupadas por año, ordenadas por cuatrimestre (las anuales al final) y nombre. Sin 'year' devuelve todos los años del grado, también los vacíos; con 'year', solo ese",
        "operationId": "getCurriculum",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del grado",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          },
          {
            "name": "year",
            "in": "query",
            "description": "Solo este año del grado",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          },
          {
            "name": "semester",
            "in": "query",
            "description": "Solo este cuatrimestre, 1 o 2",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "200": {
            "description": "Plan de estudios obtenido",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/CurriculumDto" }
              }
            }
          },
          "400": {
            "description": "'year' fuera de 1..años del grado o 'semester' distinto de 1 y 2",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/CurriculumDto" }
              }
            }
          },
          "404": {
            "description": "No existe ningún grado con ese ID",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/CurriculumDto" }
              }
            }
          }
        }
      }
    },
    "/profile": {
      "get": {
        "tags": ["Perfil"],
        "summary": "Obtiene el perfil del usuario autenticado",
        "description": "Extrae el email y el rol a partir del JWT enviado en la petición",
        "operationId": "getProfile",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UserProfile" }
              }
            }
          }
        }
      }
    },
    "/pdf/{pdfId}": {
      "get": {
        "tags": ["PDFs"],
        "summary": "Obtiene el contenido del PDF para visualizarlo",
        "description": "Devuelve el binario (application/pdf) servido desde el back, pensado para renderizarlo con pdf.js. Nunca se expone la URL de S3.",
        "operationId": "getPDF",
        "parameters": [
          {
            "name": "pdfId",
            "in": "path",
            "description": "Id del PDF",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Contenido del PDF",
            "content": {
              "*/*": { "schema": { "type": "string", "format": "binary" } }
            }
          },
          "404": {
            "description": "No existe ningún PDF con ese id",
            "content": {
              "*/*": { "schema": { "type": "string", "format": "binary" } }
            }
          }
        }
      }
    },
    "/pdf/top/me": {
      "get": {
        "tags": ["PDFs"],
        "summary": "PDFs más vistos por el usuario autenticado",
        "description": "Ordenados de más a menos aperturas hechas por el usuario del token. Si aún no ha visto ningún PDF devuelve una lista vacía (el front puede ocultar la hilera). 'viewCount' de cada PDF sigue siendo el total general",
        "operationId": "getMyTopViewedPDFs",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Máximo de PDFs a devolver (por defecto 10, máximo 20)",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de PDFs (puede estar vacía)",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PDFDto" }
                }
              }
            }
          },
          "401": {
            "description": "Sin token válido o cuenta de usuario inactiva",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PDFDto" }
                }
              }
            }
          }
        }
      }
    },
    "/pdf/recent/subscribed": {
      "get": {
        "tags": ["PDFs"],
        "summary": "PDFs nuevos o actualizados de las asignaturas a las que estoy suscrito",
        "description": "Como GET /public/pdf/recent pero solo de las asignaturas suscritas, del más reciente al más antiguo. Lista vacía si el usuario no tiene suscripciones",
        "operationId": "getRecentSubscribedPDFs",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Máximo de PDFs a devolver (por defecto 10, máximo 20)",
            "required": false,
            "schema": { "type": "integer", "format": "int32" }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de PDFs (puede estar vacía)",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PDFDto" }
                }
              }
            }
          },
          "401": {
            "description": "Sin token válido o cuenta de usuario inactiva",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PDFDto" }
                }
              }
            }
          }
        }
      }
    },
    "/option/{id}": {
      "get": {
        "tags": ["Option"],
        "summary": "Obtiene una opción por su ID",
        "description": "Incluye si la opción es correcta, por lo que es solo para edición. Requiere rol ADMIN",
        "operationId": "getOption",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la opción",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "200": {
            "description": "Opción encontrada",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          },
          "404": {
            "description": "Opción no encontrada",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          },
          "401": {
            "description": "No autorizado",
            "content": {
              "*/*": { "schema": { "$ref": "#/components/schemas/OptionDto" } }
            }
          }
        }
      }
    },
    "/notifications": {
      "get": {
        "tags": ["Notificaciones"],
        "summary": "Mis notificaciones",
        "description": "Bandeja del usuario autenticado, de la más reciente a la más antigua. No modifica la cuenta del usuario",
        "operationId": "getMyNotifications",
        "parameters": [
          {
            "name": "unreadOnly",
            "in": "query",
            "description": "Si es true, solo las no leídas",
            "required": false,
            "schema": { "type": "boolean", "default": false }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Número de página, empezando en 0",
            "required": false,
            "schema": { "type": "integer", "format": "int32", "default": 0 }
          },
          {
            "name": "size",
            "in": "query",
            "description": "Tamaño de página (por defecto 20, máximo 50)",
            "required": false,
            "schema": { "type": "integer", "format": "int32", "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "Página de notificaciones",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PageNotificationDto" }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PageNotificationDto" }
              }
            }
          }
        }
      }
    },
    "/notifications/unread-count": {
      "get": {
        "tags": ["Notificaciones"],
        "summary": "Número de notificaciones sin leer",
        "description": "Pensado para el polling de la campanita (recomendado cada 60 s con la pestaña visible). Es una consulta muy ligera y no modifica la cuenta del usuario",
        "operationId": "getUnreadCount",
        "responses": {
          "200": {
            "description": "Número de notificaciones sin leer",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UnreadCountDto" }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/UnreadCountDto" }
              }
            }
          }
        }
      }
    },
    "/me/subscriptions": {
      "get": {
        "tags": ["Suscripciones"],
        "summary": "Lista las asignaturas a las que estoy suscrito",
        "description": "Ordenadas por nombre de asignatura. Lista vacía si no hay ninguna suscripción",
        "operationId": "getMySubscriptions",
        "responses": {
          "200": {
            "description": "Suscripciones del usuario (puede estar vacía)",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SubjectSubscriptionDto"
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SubjectSubscriptionDto"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/me/pdf-ratings": {
      "get": {
        "tags": ["Valoraciones de PDFs"],
        "summary": "Mis votos en un lote de PDFs",
        "description": "Pensado para marcar los PDFs ya votados en un listado. Devuelve solo los PDFs que el usuario ha votado, en el orden pedido; los ids repetidos se ignoran. Máximo 100 ids",
        "operationId": "getMyVotes",
        "parameters": [
          {
            "name": "pdfIds",
            "in": "query",
            "description": "Ids de los PDFs separados por comas",
            "required": true,
            "schema": {
              "type": "array",
              "items": { "type": "integer", "format": "int64" }
            },
            "example": "1,2,3"
          }
        ],
        "responses": {
          "200": {
            "description": "Votos del usuario (puede estar vacía)",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/MyPdfVoteDto" }
                }
              }
            }
          },
          "400": {
            "description": "Más de 100 ids o ids mal formados",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/MyPdfVoteDto" }
                }
              }
            }
          },
          "401": {
            "description": "Sin token válido o cuenta de usuario inactiva",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/MyPdfVoteDto" }
                }
              }
            }
          }
        }
      }
    },
    "/attempts": {
      "get": {
        "tags": ["Quiz Attempts"],
        "summary": "Seleccionar mis intentos de quizzes",
        "description": "Obtiene los intentos de cuestionarios del usuario autenticado",
        "operationId": "getMyAttempts",
        "parameters": [
          {
            "name": "pageable",
            "in": "query",
            "required": true,
            "schema": { "$ref": "#/components/schemas/Pageable" }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de intentos de cuestionarios del usuario autenticado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PageQuizAttemptDto" }
              }
            }
          },
          "401": {
            "description": "Usuario no autenticado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/PageQuizAttemptDto" }
              }
            }
          }
        }
      }
    },
    "/attempts/stats": {
      "get": {
        "tags": ["Quiz Attempts"],
        "summary": "Obtener mis estadísticas de cuestionarios",
        "description": "Estadísticas agregadas de todos los intentos del usuario autenticado",
        "operationId": "getMyStats",
        "responses": {
          "200": {
            "description": "Estadísticas del usuario autenticado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuizAttemptStatsDto" }
              }
            }
          },
          "401": {
            "description": "Usuario no autenticado",
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/QuizAttemptStatsDto" }
              }
            }
          }
        }
      }
    },
    "/subject/unit/delete/{id}": {
      "delete": {
        "tags": ["Subjects"],
        "summary": "Elimina un tema de una asignatura",
        "description": "Requiere rol ADMIN",
        "operationId": "deleteSubjectUnit",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del tema a eliminar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": { "description": "Tema eliminado" },
          "404": { "description": "No existe ningún tema con ese ID" },
          "401": { "description": "El usuario autenticado no tiene rol ADMIN" },
          "409": {
            "description": "No se puede eliminar el tema porque tiene PDFs asociados"
          }
        }
      }
    },
    "/subject/delete/{id}": {
      "delete": {
        "tags": ["Subjects"],
        "summary": "Elimina una asignatura del catálogo",
        "description": "Requiere rol ADMIN",
        "operationId": "deleteSubject",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la asignatura a eliminar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": { "description": "Asignatura eliminada" },
          "404": { "description": "No existe ninguna asignatura con ese ID" },
          "409": {
            "description": "No se puede eliminar la asignatura porque tiene temas asociados"
          },
          "401": { "description": "El usuario autenticado no tiene rol ADMIN" }
        }
      }
    },
    "/quiz/delete/{id}": {
      "delete": {
        "tags": ["Quiz"],
        "summary": "Elimina un cuestionario y sus preguntas asociadas por su ID",
        "description": "Requiere rol ADMIN",
        "operationId": "deleteQuiz",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del cuestionario a eliminar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": { "description": "Cuestionario eliminado correctamente" },
          "401": { "description": "No autorizado" },
          "404": {
            "description": "No existe ningún cuestionario con el ID proporcionado"
          }
        }
      }
    },
    "/question/delete/{id}": {
      "delete": {
        "tags": ["Question"],
        "summary": "Elimina una pregunta por su ID",
        "description": "Requiere rol ADMIN",
        "operationId": "deleteQuestion",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la pregunta a eliminar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": { "description": "Pregunta eliminada" },
          "401": { "description": "No autorizado" },
          "404": { "description": "Pregunta no encontrada" }
        }
      }
    },
    "/pdf/delete/{pdfId}": {
      "delete": {
        "tags": ["PDFs"],
        "summary": "Borra un PDF (metadatos y fichero en S3)",
        "description": "Requiere rol ADMIN",
        "operationId": "deletePDF",
        "parameters": [
          {
            "name": "pdfId",
            "in": "path",
            "description": "Id del PDF a borrar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": { "description": "PDF borrado" },
          "401": { "description": "El usuario autenticado no tiene rol ADMIN" },
          "404": { "description": "No existe ningún PDF con ese id" }
        }
      }
    },
    "/option/delete/{id}": {
      "delete": {
        "tags": ["Option"],
        "summary": "Elimina una opción",
        "description": "Requiere rol ADMIN",
        "operationId": "deleteOption",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID de la opción a eliminar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": { "description": "Opción eliminada correctamente" },
          "401": { "description": "No autorizado" },
          "404": {
            "description": "No existe ninguna opción con el ID proporcionado"
          }
        }
      }
    },
    "/notifications/{id}": {
      "delete": {
        "tags": ["Notificaciones"],
        "summary": "Borra una notificación",
        "description": "Solo la quita de la bandeja del usuario",
        "operationId": "delete",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Id de la notificación",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": { "description": "Borrada" },
          "401": { "description": "No autenticado" },
          "404": { "description": "No existe o no es del usuario" }
        }
      }
    },
    "/degree/delete/{id}": {
      "delete": {
        "tags": ["Degrees"],
        "summary": "Elimina un grado del catálogo",
        "description": "Requiere rol ADMIN. Los usuarios que lo tenían en su perfil se quedan sin grado ni curso",
        "operationId": "deleteDegree",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "ID del grado a eliminar",
            "required": true,
            "schema": { "type": "integer", "format": "int64" }
          }
        ],
        "responses": {
          "204": { "description": "Grado eliminado" },
          "404": { "description": "No existe ningún grado con ese ID" },
          "409": {
            "description": "No se puede eliminar el grado porque tiene asignaturas colocadas"
          },
          "401": { "description": "El usuario autenticado no tiene rol ADMIN" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SubjectPlacementDto": {
        "type": "object",
        "properties": {
          "degreeId": {
            "type": "integer",
            "format": "int64",
            "description": "ID del grado en el que se coloca la asignatura. Un mismo grado no puede repetirse en la lista",
            "example": 1
          },
          "year": {
            "type": "integer",
            "format": "int32",
            "description": "Año (curso) del grado en el que se cursa, entre 1 y los años del grado",
            "example": 4,
            "minimum": 1
          },
          "semester": {
            "type": ["integer", "null"],
            "format": "int32",
            "description": "Cuatrimestre: 1 o 2. Nulo si la asignatura es anual o no se especifica",
            "example": 1,
            "maximum": 2,
            "minimum": 1
          }
        },
        "required": ["degreeId", "year"]
      },
      "UpdateSubjectDto": {
        "type": "object",
        "description": "Datos para actualizar la asignatura",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nombre único de la asignatura dentro del catálogo",
            "example": "Cálculo Diferencial e Integral",
            "minLength": 1
          },
          "description": {
            "type": "string",
            "description": "Descripción opcional de la asignatura",
            "maxLength": 500,
            "minLength": 0
          },
          "placements": {
            "type": ["array", "null"],
            "description": "Colocaciones de la asignatura en grados (opcional). En la edición, nulo conserva las colocaciones actuales y una lista (también vacía) las reemplaza todas",
            "items": { "$ref": "#/components/schemas/SubjectPlacementDto" }
          }
        },
        "required": ["name"]
      },
      "SubjectDetailDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno de la asignatura",
            "readOnly": true
          },
          "name": {
            "type": "string",
            "description": "Nombre único de la asignatura"
          },
          "description": {
            "type": "string",
            "description": "Descripción opcional de la asignatura"
          },
          "placements": {
            "type": "array",
            "description": "Grados en los que está colocada la asignatura. Lista vacía si no está en ninguno",
            "items": { "$ref": "#/components/schemas/SubjectPlacementInfoDto" }
          }
        }
      },
      "SubjectPlacementInfoDto": {
        "type": "object",
        "properties": {
          "degreeId": {
            "type": "integer",
            "format": "int64",
            "description": "ID del grado",
            "example": 1
          },
          "degreeName": {
            "type": "string",
            "description": "Nombre del grado",
            "example": "Grado en Matemáticas"
          },
          "university": {
            "type": ["string", "null"],
            "description": "Universidad del grado (puede ser nula)",
            "example": "Universidad de Sevilla"
          },
          "year": {
            "type": "integer",
            "format": "int32",
            "description": "Año (curso) del grado en el que se cursa",
            "example": 4
          },
          "semester": {
            "type": ["integer", "null"],
            "format": "int32",
            "description": "Cuatrimestre (1 o 2). Nulo si la asignatura es anual o no se especifica",
            "example": 1
          }
        }
      },
      "UpdateSubjectUnitDto": {
        "type": "object",
        "description": "Datos para actualizar el tema",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nombre único del tema dentro de la asignatura",
            "example": "Tema 1: Límites y Continuidad",
            "minLength": 1
          },
          "position": {
            "type": "integer",
            "format": "int32",
            "description": "Posición del tema dentro del orden de la asignatura",
            "example": 1
          }
        },
        "required": ["name"]
      },
      "SubjectUnitDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno del tema",
            "readOnly": true
          },
          "name": { "type": "string", "description": "Nombre del tema" },
          "position": {
            "type": "integer",
            "format": "int32",
            "description": "Posición del tema dentro del orden de la asignatura"
          }
        }
      },
      "UpdateQuizDto": {
        "type": "object",
        "description": "Datos del cuestionario a actualizar",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nombre del cuestionario",
            "example": "Cuestionario de Álgebra Lineal",
            "minLength": 1
          },
          "description": {
            "type": ["string", "null"],
            "description": "Descripción del cuestionario",
            "example": "Cuestionario sobre operaciones con matrices",
            "maxLength": 500,
            "minLength": 0
          },
          "difficulty": {
            "type": "string",
            "description": "Dificultad del cuestionario",
            "enum": ["EASY", "MEDIUM", "HARD"],
            "example": "EASY|MEDIUM|HARD"
          },
          "subjectId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador de la asignatura a la que pertenece el cuestionario",
            "example": 1
          },
          "subjectUnitId": {
            "type": ["integer", "null"],
            "format": "int64",
            "description": "Identificador del tema al que pertenece el cuestionario",
            "example": 1
          }
        },
        "required": ["difficulty", "name", "subjectId"]
      },
      "QuizDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno del cuestionario",
            "readOnly": true
          },
          "name": {
            "type": "string",
            "description": "Nombre del cuestionario"
          },
          "description": {
            "type": "string",
            "description": "Descripción opcional del cuestionario"
          },
          "difficulty": {
            "type": "string",
            "description": "Dificultad del cuestionario",
            "enum": ["EASY", "MEDIUM", "HARD"]
          },
          "lastTimeEdited": {
            "type": "string",
            "format": "date-time",
            "description": "Fecha de última edición del cuestionario",
            "readOnly": true
          },
          "subject": {
            "$ref": "#/components/schemas/SubjectDto",
            "description": "Asignatura a la que pertenece el cuestionario"
          },
          "subjectUnit": {
            "type": "null",
            "$ref": "#/components/schemas/SubjectUnitDto",
            "description": "Tema al que pertenece el cuestionario"
          },
          "visible": {
            "type": "boolean",
            "description": "Si el cuestionario es visible para los usuarios. Los ocultos solo los ve un administrador"
          },
          "publishedAt": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "Fecha de la primera publicación (primera vez que se hizo visible). Nula si nunca se ha publicado",
            "readOnly": true
          },
          "attemptCount": {
            "type": "integer",
            "format": "int64",
            "description": "Número total de veces que se ha hecho el cuestionario (todos los usuarios; cada envío cuenta, aunque sea del mismo usuario). 0 si nadie lo ha hecho",
            "example": 128,
            "readOnly": true
          }
        }
      },
      "SubjectDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno de la asignatura",
            "readOnly": true
          },
          "name": {
            "type": "string",
            "description": "Nombre único de la asignatura"
          },
          "description": {
            "type": "string",
            "description": "Descripción opcional de la asignatura"
          }
        }
      },
      "UpdateQuestionDto": {
        "type": "object",
        "description": "Datos de la pregunta a actualizar",
        "properties": {
          "text": {
            "type": "string",
            "description": "Texto de la pregunta",
            "example": "¿Cuál es la capital de Francia?",
            "minLength": 1
          },
          "type": {
            "type": "string",
            "description": "Tipo de la pregunta (multiple choice, true/false, etc.)",
            "enum": ["MULTIPLE_CHOICE", "TRUE_FALSE"],
            "example": "MULTIPLE_CHOICE"
          },
          "position": {
            "type": "integer",
            "format": "int32",
            "description": "Posición de la pregunta en el cuestionario",
            "example": 1
          },
          "explanation": {
            "type": ["string", "null"],
            "description": "Explicación de la respuesta correcta de la pregunta",
            "example": "La capital de Francia es París."
          },
          "quizId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador del cuestionario al que pertenece la pregunta",
            "example": 1
          }
        },
        "required": ["quizId", "text", "type"]
      },
      "QuestionDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno de la pregunta",
            "readOnly": true
          },
          "text": { "type": "string", "description": "Texto de la pregunta" },
          "type": {
            "type": "string",
            "description": "Tipo de la pregunta (multiple choice, true/false, etc.)",
            "enum": ["MULTIPLE_CHOICE", "TRUE_FALSE"]
          },
          "explanation": {
            "type": "string",
            "description": "Explicación de la respuesta correcta de la pregunta"
          },
          "position": {
            "type": "integer",
            "format": "int32",
            "description": "Posición de la pregunta en el cuestionario"
          },
          "quizId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador del cuestionario al que pertenece la pregunta"
          }
        }
      },
      "RatePdfDto": {
        "type": "object",
        "properties": {
          "vote": {
            "type": "string",
            "description": "Voto: LIKE (👍) o DISLIKE (👎)",
            "enum": ["LIKE", "DISLIKE"],
            "example": "LIKE"
          }
        },
        "required": ["vote"]
      },
      "PdfRatingDto": {
        "type": "object",
        "properties": {
          "pdfId": {
            "type": "integer",
            "format": "int64",
            "description": "Id del PDF",
            "example": 7
          },
          "rating": {
            "$ref": "#/components/schemas/PdfRatingSummaryDto",
            "description": "Resumen público de valoraciones del PDF"
          },
          "myVote": {
            "type": ["string", "null"],
            "description": "Voto del usuario autenticado. Nulo si no ha votado",
            "enum": ["LIKE", "DISLIKE"],
            "example": "LIKE"
          },
          "canVote": {
            "type": "boolean",
            "description": "Si el usuario autenticado puede votar (o cambiar su voto) ahora mismo en este PDF",
            "example": true
          },
          "cannotVoteReason": {
            "type": ["string", "null"],
            "description": "Por qué no puede votar. Nulo si puede. AUTHOR (es autor del PDF) tiene prioridad sobre NOT_VIEWED (no lo ha abierto todavía)",
            "enum": ["NOT_VIEWED", "AUTHOR"],
            "example": "NOT_VIEWED"
          }
        }
      },
      "PdfRatingSummaryDto": {
        "type": "object",
        "properties": {
          "likeCount": {
            "type": "integer",
            "format": "int64",
            "description": "Número de votos positivos (👍)",
            "example": 12
          },
          "dislikeCount": {
            "type": "integer",
            "format": "int64",
            "description": "Número de votos negativos (👎)",
            "example": 2
          },
          "score": {
            "type": "number",
            "format": "double",
            "description": "Límite inferior de Wilson de la proporción de 👍 (0..1), usado para ordenar. 0 si no hay votos",
            "example": 0.69
          }
        }
      },
      "UpdatePDFDto": {
        "type": "object",
        "description": "Datos del PDF a actualizar",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nombre único del PDF dentro del catálogo",
            "example": "CDI: Tema 3 - Integrales",
            "minLength": 1
          },
          "description": {
            "type": "string",
            "description": "Descripción del contenido del PDF",
            "example": "Este PDF contiene ejercicios resueltos de integrales para el tema 3 del curso de CDI."
          },
          "subjectId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador de la asignatura a la que pertenece el PDF"
          },
          "subjectUnitId": {
            "type": ["integer", "null"],
            "format": "int64",
            "description": "Identificador de la unidad temática a la que pertenece el PDF. En caso de que el PDF sea general para toda la asignatura, este campo puede ser nulo."
          },
          "authorEmails": {
            "type": "array",
            "description": "Emails de los usuarios autores. El primero es el autor principal (obligatorio); el resto, coautores (opcionales)",
            "example": ["autor@mathtexpedia.es", "coautor@mathtexpedia.es"],
            "items": { "type": "string", "minLength": 1 },
            "minItems": 1
          }
        },
        "required": ["authorEmails", "name", "subjectId"]
      },
      "AuthorDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno del usuario; sirve para pedir su foto en GET /users/{id}/avatar",
            "example": 42
          },
          "username": {
            "type": ["string", "null"],
            "description": "Nombre público. Nulo si el usuario aún no ha completado su perfil",
            "example": "ada_lovelace"
          },
          "hasAvatar": {
            "type": "boolean",
            "description": "Si tiene foto de perfil"
          },
          "avatarUpdatedAt": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "Versión de la foto (cuándo se cambió); clave de caché. Nulo si no tiene"
          }
        }
      },
      "PDFDto": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "format": "int64" },
          "name": { "type": "string" },
          "lastTimeEdited": { "type": "string", "format": "date-time" },
          "description": { "type": "string" },
          "subject": { "$ref": "#/components/schemas/SubjectDto" },
          "subjectUnit": { "$ref": "#/components/schemas/SubjectUnitDto" },
          "author": {
            "type": ["string", "null"],
            "description": "Nombre público (username) del autor principal. Nulo en PDFs antiguos que aún no tienen autores asignados o si el autor no ha completado su perfil",
            "example": "ada_lovelace"
          },
          "coauthors": {
            "type": "array",
            "description": "Nombres públicos de los coautores, en el orden en que se indicaron. Vacío si no hay coautores. Un coautor sin perfil completo aparece como nulo",
            "items": { "type": ["string", "null"] }
          },
          "authors": {
            "type": "array",
            "description": "Autores con su identificador y marca de foto de perfil: el primero es el principal, el resto coautores, en el mismo orden que 'author' y 'coauthors'. Vacío en PDFs antiguos sin autores",
            "items": { "$ref": "#/components/schemas/AuthorDto" }
          },
          "viewCount": {
            "type": "integer",
            "format": "int64",
            "description": "Número total de veces que se ha abierto el PDF (todos los usuarios; cada apertura cuenta, aunque sea del mismo usuario). 0 si nunca se ha visto",
            "example": 42
          },
          "rating": {
            "$ref": "#/components/schemas/PdfRatingSummaryDto",
            "description": "Resumen público de valoraciones (👍/👎). Nunca dice quién votó"
          }
        }
      },
      "UpdateOptionDto": {
        "type": "object",
        "description": "Datos de la opción a actualizar",
        "properties": {
          "text": {
            "type": "string",
            "description": "Texto de la opción",
            "minLength": 1
          },
          "position": {
            "type": "integer",
            "format": "int32",
            "description": "Posición de la opción en la pregunta"
          },
          "questionId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador de la pregunta a la que pertenece la opción"
          },
          "correct": { "type": "boolean" }
        },
        "required": ["questionId", "text"]
      },
      "OptionDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno de la opción",
            "readOnly": true
          },
          "text": { "type": "string", "description": "Texto de la opción" },
          "position": {
            "type": "integer",
            "format": "int32",
            "description": "Posición de la opción en la pregunta"
          },
          "questionId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador de la pregunta a la que pertenece la opción"
          },
          "correct": { "type": "boolean" }
        }
      },
      "Item": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Tipo de notificación (debe ser configurable)",
            "enum": [
              "PDF_CREATED",
              "PDF_FILE_UPDATED",
              "QUIZ_PUBLISHED",
              "SUBJECT_CREATED",
              "SUBJECT_UNIT_CREATED",
              "PDF_AUTHOR_ADDED",
              "WELCOME",
              "ANNOUNCEMENT"
            ],
            "example": "PDF_CREATED"
          },
          "channel": {
            "type": "string",
            "description": "Canal",
            "enum": ["IN_APP"],
            "example": "IN_APP"
          },
          "enabled": {
            "type": "boolean",
            "description": "Si se quiere recibir"
          },
          "scope": {
            "type": ["string", "null"],
            "description": "Alcance (opcional; debe estar entre los admitidos por el tipo). Si no se indica se mantiene el actual",
            "enum": ["ALL", "SUBSCRIBED"],
            "example": "ALL"
          }
        },
        "required": ["channel", "enabled", "type"]
      },
      "UpdateNotificationPreferencesDto": {
        "type": "object",
        "properties": {
          "preferences": {
            "type": "array",
            "description": "Preferencias a cambiar. Es parcial: solo se tocan las indicadas",
            "items": { "$ref": "#/components/schemas/Item" },
            "minItems": 1
          }
        },
        "required": ["preferences"]
      },
      "NotificationPreferenceDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Tipo de notificación",
            "enum": [
              "PDF_CREATED",
              "PDF_FILE_UPDATED",
              "QUIZ_PUBLISHED",
              "SUBJECT_CREATED",
              "SUBJECT_UNIT_CREATED",
              "PDF_AUTHOR_ADDED",
              "WELCOME",
              "ANNOUNCEMENT"
            ],
            "example": "PDF_CREATED"
          },
          "category": {
            "type": "string",
            "description": "Categoría, para agrupar en la pantalla de preferencias",
            "enum": ["CONTENT", "PERSONAL", "SYSTEM"],
            "example": "CONTENT"
          },
          "label": {
            "type": "string",
            "description": "Nombre corto para mostrar",
            "example": "Nuevos apuntes"
          },
          "description": {
            "type": "string",
            "description": "Descripción para mostrar",
            "example": "Cuando se sube un apunte nuevo"
          },
          "channel": {
            "type": "string",
            "description": "Canal de entrega",
            "enum": ["IN_APP"],
            "example": "IN_APP"
          },
          "enabled": {
            "type": "boolean",
            "description": "Si el usuario recibe este tipo por este canal"
          },
          "defaultEnabled": {
            "type": "boolean",
            "description": "Valor por defecto, para poder mostrar 'restablecer'"
          },
          "scope": {
            "type": ["string", "null"],
            "description": "Alcance elegido. Nulo si el tipo no admite alcances",
            "enum": ["ALL", "SUBSCRIBED"],
            "example": "ALL"
          },
          "availableScopes": {
            "type": "array",
            "description": "Alcances que admite el tipo. Si solo hay uno no hace falta mostrar selector",
            "items": { "type": "string", "enum": ["ALL", "SUBSCRIBED"] },
            "uniqueItems": true
          }
        }
      },
      "UpdateUserAccountDto": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "description": "Nombre público que se muestra en la aplicación (apuntes, búsquedas…). Obligatorio, único sin distinguir mayúsculas, de 3 a 30 caracteres entre letras sin tilde, números, punto, guion y guion bajo",
            "example": "ada_lovelace",
            "minLength": 1,
            "pattern": "^[A-Za-z0-9._-]{3,30}$"
          },
          "firstName": {
            "type": ["string", "null"],
            "description": "Nombre de pila (opcional). Nulo o vacío lo borra",
            "example": "Ada",
            "maxLength": 100,
            "minLength": 0
          },
          "lastName": {
            "type": ["string", "null"],
            "description": "Apellidos (opcional). Nulo o vacío lo borra",
            "example": "Lovelace",
            "maxLength": 100,
            "minLength": 0
          },
          "bio": {
            "type": ["string", "null"],
            "description": "Biografía corta (opcional, máx. 280 caracteres). Nulo o vacío la borra",
            "maxLength": 280,
            "minLength": 0
          },
          "university": {
            "type": ["string", "null"],
            "description": "Universidad o centro de estudios (opcional). Nulo o vacío lo borra",
            "example": "Universidad de Sevilla",
            "maxLength": 150,
            "minLength": 0
          },
          "studies": {
            "type": ["string", "null"],
            "description": "Estudios que cursa (opcional). Nulo o vacío lo borra",
            "example": "Grado en Matemáticas",
            "maxLength": 150,
            "minLength": 0
          },
          "degreeId": {
            "type": ["integer", "null"],
            "format": "int64",
            "description": "Identificador de un grado del catálogo (GET /public/degree). Opcional: nulo lo borra. 404 si no existe",
            "example": 1
          },
          "currentYear": {
            "type": ["integer", "null"],
            "format": "int32",
            "description": "Curso del grado en el que está (de 1 al número de años del grado). Opcional: nulo lo borra. Exige degreeId (400 si falta) y no puede superar los años del grado (400)",
            "example": 3,
            "minimum": 1
          }
        },
        "required": ["username"]
      },
      "DegreeDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno del grado",
            "readOnly": true
          },
          "name": {
            "type": "string",
            "description": "Nombre del grado",
            "example": "Grado en Matemáticas"
          },
          "university": {
            "type": ["string", "null"],
            "description": "Universidad en la que se cursa (texto libre, opcional)",
            "example": "Universidad de Sevilla"
          },
          "years": {
            "type": "integer",
            "format": "int32",
            "description": "Número de años (cursos) del grado. Los años son los enteros de 1 a este valor",
            "example": 4
          }
        }
      },
      "UserAccountDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno del usuario",
            "readOnly": true
          },
          "email": {
            "type": "string",
            "description": "Email del usuario",
            "example": "user@example.com"
          },
          "username": {
            "type": ["string", "null"],
            "description": "Nombre público del usuario. Nulo hasta que completa el perfil",
            "example": "ada_lovelace"
          },
          "firstName": {
            "type": ["string", "null"],
            "description": "Nombre de pila",
            "example": "Ada"
          },
          "lastName": {
            "type": ["string", "null"],
            "description": "Apellidos",
            "example": "Lovelace"
          },
          "bio": {
            "type": ["string", "null"],
            "description": "Biografía corta"
          },
          "university": {
            "type": ["string", "null"],
            "description": "Universidad o centro de estudios",
            "example": "Universidad de Sevilla"
          },
          "studies": {
            "type": ["string", "null"],
            "description": "Estudios que cursa",
            "example": "Grado en Matemáticas"
          },
          "degree": {
            "type": "null",
            "$ref": "#/components/schemas/DegreeDto",
            "description": "Grado del catálogo que cursa. Nulo si no lo ha elegido"
          },
          "currentYear": {
            "type": ["integer", "null"],
            "format": "int32",
            "description": "Curso del grado en el que está (de 1 a degree.years). Nulo si no lo ha indicado o no tiene grado",
            "example": 3
          },
          "hasAvatar": {
            "type": "boolean",
            "description": "Si el usuario tiene foto de perfil. Se descarga de GET /users/{id}/avatar"
          },
          "avatarUpdatedAt": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "Cuándo se cambió la foto por última vez; nulo si no tiene. Úsalo como clave de caché de la imagen"
          },
          "status": {
            "type": "string",
            "description": "Estado del usuario",
            "enum": ["ACTIVE", "INACTIVE", "SUSPENDED"],
            "example": "ACTIVE"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Fecha de creación del usuario",
            "readOnly": true
          },
          "lastSeenAt": {
            "type": "string",
            "format": "date-time",
            "description": "Fecha del último acceso del usuario"
          },
          "profileCompletedAt": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "Fecha en que se completó el perfil (se fija al guardar por primera vez un nombre de usuario). Nulo = el perfil está por completar y el front debe pedirlo"
          }
        }
      },
      "SubjectSubscriptionDto": {
        "type": "object",
        "properties": {
          "subject": {
            "$ref": "#/components/schemas/SubjectDto",
            "description": "Asignatura a la que está suscrito el usuario"
          },
          "subscribedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Cuándo se suscribió"
          }
        }
      },
      "UpdateDegreeDto": {
        "type": "object",
        "description": "Datos para actualizar el grado",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nombre del grado. Único, sin distinguir mayúsculas, junto con la universidad",
            "example": "Grado en Matemáticas",
            "maxLength": 150,
            "minLength": 0
          },
          "university": {
            "type": ["string", "null"],
            "description": "Universidad en la que se cursa (opcional). Nulo o vacío lo borra",
            "example": "Universidad de Sevilla",
            "maxLength": 150,
            "minLength": 0
          },
          "years": {
            "type": "integer",
            "format": "int32",
            "description": "Número de años (cursos) del grado, entre 1 y 10",
            "example": 4,
            "maximum": 10,
            "minimum": 1
          }
        },
        "required": ["name", "years"]
      },
      "CreateSubjectUnitDto": {
        "type": "object",
        "description": "Datos del tema a crear",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nombre único del tema dentro de la asignatura",
            "example": "Tema 1: Límites y Continuidad",
            "minLength": 1
          },
          "position": {
            "type": "integer",
            "format": "int32",
            "description": "Posición del tema dentro del orden de la asignatura",
            "example": 1
          }
        },
        "required": ["name"]
      },
      "CreateSubjectDto": {
        "type": "object",
        "description": "Datos de la asignatura a crear",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nombre único de la asignatura dentro del catálogo",
            "example": "Cálculo Diferencial e Integral",
            "minLength": 1
          },
          "description": {
            "type": "string",
            "description": "Descripción opcional de la asignatura",
            "maxLength": 500,
            "minLength": 0
          },
          "placements": {
            "type": ["array", "null"],
            "description": "Colocaciones de la asignatura en grados (opcional). En el alta, nulo o vacío deja la asignatura sin colocaciones",
            "items": { "$ref": "#/components/schemas/SubjectPlacementDto" }
          }
        },
        "required": ["name"]
      },
      "AttemptAnswerSubmissionDto": {
        "type": "object",
        "properties": {
          "questionId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador de la pregunta a la que corresponde la respuesta",
            "example": 1
          },
          "selectedOptionId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador de la opción seleccionada como respuesta",
            "example": 2
          }
        }
      },
      "SubmitQuizAttemptDto": {
        "type": "object",
        "description": "Intento de cuestionario a enviar",
        "properties": {
          "answers": {
            "type": "array",
            "description": "Lista de respuestas del intento de quiz",
            "items": {
              "$ref": "#/components/schemas/AttemptAnswerSubmissionDto"
            }
          }
        }
      },
      "AttemptAnswerResultDto": {
        "type": "object",
        "properties": {
          "questionId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno de la pregunta del intento de respuesta",
            "example": 1
          },
          "selectedOptionId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno de la respuesta seleccionada en el intento de respuesta",
            "example": 2
          },
          "correctOptionId": {
            "type": "integer",
            "format": "int64",
            "description": "Opción correcta de la pregunta del intento de respuesta",
            "example": 3
          },
          "explanation": {
            "type": "string",
            "description": "Explicación de la respuesta correcta, si existe",
            "example": "La respuesta correcta es la opción 3 porque..."
          },
          "correct": { "type": "boolean" }
        }
      },
      "QuizAttemptResultDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno del intento de cuestionario",
            "example": 1
          },
          "score": {
            "type": "number",
            "format": "double",
            "description": "Puntuación obtenida en el intento de cuestionario",
            "example": 85.5
          },
          "adjustedScore": {
            "type": "number",
            "format": "double",
            "description": "Puntuación ponderada según el número de intento; es la que cuenta para el leaderboard",
            "example": 6.0
          },
          "attemptNumber": {
            "type": "integer",
            "format": "int32",
            "description": "Número de intento del usuario en este cuestionario (1 = primer intento)",
            "example": 2
          },
          "totalQuestions": {
            "type": "integer",
            "format": "int32",
            "description": "Número total de preguntas en el intento de cuestionario",
            "example": 10
          },
          "correctAnswers": {
            "type": "integer",
            "format": "int32",
            "description": "Número de respuestas correctas en el intento de cuestionario",
            "example": 8
          },
          "incorrectAnswers": {
            "type": "integer",
            "format": "int32",
            "description": "Número de respuestas incorrectas en el intento de cuestionario",
            "example": 2
          },
          "unansweredQuestions": {
            "type": "integer",
            "format": "int32",
            "description": "Número de preguntas no respondidas en el intento de cuestionario",
            "example": 0
          },
          "percentage": {
            "type": "number",
            "format": "double",
            "description": "Porcentaje de respuestas correctas en el intento de cuestionario",
            "example": 85.0
          },
          "answers": {
            "type": "array",
            "description": "Lista de respuestas del intento de cuestionario",
            "items": { "$ref": "#/components/schemas/AttemptAnswerResultDto" }
          }
        }
      },
      "ImportQuestionsDto": {
        "type": "object",
        "description": "Preguntas a añadir",
        "properties": {
          "questions": {
            "type": "array",
            "description": "Preguntas a añadir al final del cuestionario, en el orden de la lista. Se ignora la position de cada pregunta y de cada opción: se numeran según su orden en la lista",
            "items": { "$ref": "#/components/schemas/QuestionExportableDto" },
            "minItems": 1
          }
        },
        "required": ["questions"]
      },
      "OptionExportableDto": {
        "type": "object",
        "properties": {
          "text": { "type": "string", "minLength": 1 },
          "correct": { "type": "boolean" },
          "position": { "type": "integer", "format": "int32" }
        },
        "required": ["text"]
      },
      "QuestionExportableDto": {
        "type": "object",
        "properties": {
          "text": { "type": "string", "minLength": 1 },
          "position": { "type": "integer", "format": "int32" },
          "type": {
            "type": "string",
            "enum": ["MULTIPLE_CHOICE", "TRUE_FALSE"]
          },
          "explanation": { "type": "string" },
          "options": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/OptionExportableDto" },
            "minItems": 1
          }
        },
        "required": ["options", "text", "type"]
      },
      "QuizExportableDto": {
        "type": "object",
        "description": "Cuestionario a importar",
        "properties": {
          "name": { "type": "string", "minLength": 1 },
          "description": { "type": "string", "maxLength": 500, "minLength": 0 },
          "difficulty": {
            "type": "string",
            "enum": ["EASY", "MEDIUM", "HARD"]
          },
          "questions": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/QuestionExportableDto" },
            "minItems": 1
          }
        },
        "required": ["difficulty", "name", "questions"]
      },
      "CreateQuizDto": {
        "type": "object",
        "description": "Datos del cuestionario a crear",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nombre del cuestionario",
            "example": "Cuestionario de Álgebra Lineal",
            "minLength": 1
          },
          "description": {
            "type": ["string", "null"],
            "description": "Descripción del cuestionario",
            "example": "Cuestionario sobre operaciones con matrices",
            "maxLength": 500,
            "minLength": 0
          },
          "difficulty": {
            "type": "string",
            "description": "Dificultad del cuestionario",
            "enum": ["EASY", "MEDIUM", "HARD"],
            "example": "EASY|MEDIUM|HARD"
          },
          "subjectId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador de la asignatura a la que pertenece el cuestionario",
            "example": 1
          },
          "subjectUnitId": {
            "type": ["integer", "null"],
            "format": "int64",
            "description": "Identificador del tema al que pertenece el cuestionario",
            "example": 1
          }
        },
        "required": ["difficulty", "name", "subjectId"]
      },
      "CreateQuestionDto": {
        "type": "object",
        "description": "Datos de la pregunta a crear",
        "properties": {
          "text": {
            "type": "string",
            "description": "Texto de la pregunta",
            "example": "¿Cuál es la capital de Francia?",
            "minLength": 1
          },
          "type": {
            "type": "string",
            "description": "Tipo de la pregunta (multiple choice, true/false, etc.)",
            "enum": ["MULTIPLE_CHOICE", "TRUE_FALSE"],
            "example": "MULTIPLE_CHOICE"
          },
          "position": {
            "type": "integer",
            "format": "int32",
            "description": "Posición de la pregunta en el cuestionario",
            "example": 1
          },
          "explanation": {
            "type": ["string", "null"],
            "description": "Explicación de la respuesta correcta de la pregunta",
            "example": "La capital de Francia es París."
          },
          "quizId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador del cuestionario al que pertenece la pregunta",
            "example": 1
          }
        },
        "required": ["quizId", "text", "type"]
      },
      "CreatePDFDto": {
        "type": "object",
        "description": "Datos del PDF a crear",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nombre único del PDF dentro del catálogo",
            "example": "CDI: Tema 3 - Integrales",
            "minLength": 1
          },
          "subjectId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador de la asignatura a la que pertenece el PDF"
          },
          "subjectUnitId": {
            "type": ["integer", "null"],
            "format": "int64",
            "description": "Identificador de la unidad temática a la que pertenece el PDF. En caso de que el PDF sea general para toda la asignatura, este campo puede ser nulo."
          },
          "description": {
            "type": "string",
            "description": "Descripción opcional del contenido del PDF"
          },
          "authorEmails": {
            "type": "array",
            "description": "Emails de los usuarios autores. El primero es el autor principal (obligatorio); el resto, coautores (opcionales)",
            "example": ["autor@mathtexpedia.es", "coautor@mathtexpedia.es"],
            "items": { "type": "string", "minLength": 1 },
            "minItems": 1
          }
        },
        "required": ["authorEmails", "name", "subjectId"]
      },
      "CreateOptionDto": {
        "type": "object",
        "description": "Datos de la opción a crear",
        "properties": {
          "text": {
            "type": "string",
            "description": "Texto de la opción",
            "minLength": 1
          },
          "position": {
            "type": "integer",
            "format": "int32",
            "description": "Posición de la opción en la pregunta"
          },
          "questionId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador de la pregunta a la que pertenece la opción"
          },
          "correct": { "type": "boolean" }
        },
        "required": ["questionId", "text"]
      },
      "CreateAnnouncementDto": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Título del aviso",
            "example": "Mantenimiento programado",
            "maxLength": 120,
            "minLength": 0
          },
          "message": {
            "type": "string",
            "description": "Texto del aviso",
            "example": "El sábado la plataforma estará en mantenimiento de 2:00 a 4:00.",
            "maxLength": 500,
            "minLength": 0
          },
          "link": {
            "type": ["string", "null"],
            "description": "Ruta interna del front a la que llevará el aviso (debe empezar por '/'). Opcional",
            "example": "/dashboard",
            "maxLength": 300,
            "minLength": 0
          },
          "recipientEmails": {
            "type": ["array", "null"],
            "description": "Emails de los destinatarios. Si no se indica o está vacío, se envía a todos los usuarios activos",
            "items": { "type": "string", "format": "email" }
          }
        },
        "required": ["message", "title"]
      },
      "Mail": {
        "type": "object",
        "properties": {
          "from": {
            "type": ["string", "null"],
            "description": "Remitente. Si no se indica, se usa el email del usuario autenticado"
          },
          "subject": {
            "type": "string",
            "description": "Asunto del correo",
            "minLength": 1
          },
          "body": {
            "type": "string",
            "description": "Cuerpo del correo",
            "minLength": 1
          }
        },
        "required": ["body", "subject"]
      },
      "CreateDegreeDto": {
        "type": "object",
        "description": "Datos del grado a crear",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nombre del grado. Único, sin distinguir mayúsculas, junto con la universidad",
            "example": "Grado en Matemáticas",
            "maxLength": 150,
            "minLength": 0
          },
          "university": {
            "type": ["string", "null"],
            "description": "Universidad en la que se cursa (opcional). Nulo o vacío lo borra",
            "example": "Universidad de Sevilla",
            "maxLength": 150,
            "minLength": 0
          },
          "years": {
            "type": "integer",
            "format": "int32",
            "description": "Número de años (cursos) del grado, entre 1 y 10",
            "example": 4,
            "maximum": 10,
            "minimum": 1
          }
        },
        "required": ["name", "years"]
      },
      "ChatMessage": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "description": "Quién emitió el mensaje",
            "enum": ["user", "assistant"],
            "minLength": 1,
            "pattern": "user|assistant"
          },
          "content": {
            "type": "string",
            "description": "Contenido del mensaje",
            "minLength": 1
          }
        },
        "required": ["content", "role"]
      },
      "ChatRequest": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Mensaje del usuario para el chatbot",
            "example": "¿Qué es una matriz diagonalizable?",
            "minLength": 1
          },
          "conversationHistory": {
            "type": ["array", "null"],
            "description": "Historial de la conversación, en orden cronológico. Opcional",
            "items": { "$ref": "#/components/schemas/ChatMessage" }
          }
        },
        "required": ["message"]
      },
      "ChatResource": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Tipo de contenido al que apunta el recurso",
            "enum": ["PDF", "BLOG_POST", "PAGE"]
          },
          "title": { "type": "string", "description": "Título del recurso" },
          "url": {
            "type": "string",
            "description": "URL del recurso en Mathtexpedia"
          }
        }
      },
      "ChatResponse": {
        "type": "object",
        "properties": {
          "response": {
            "type": "string",
            "description": "Respuesta generada por el chatbot"
          },
          "relevantResources": {
            "type": "array",
            "description": "Recursos de Mathtexpedia relevantes para la respuesta",
            "items": { "$ref": "#/components/schemas/ChatResource" }
          },
          "status": {
            "type": "string",
            "description": "Resultado de la operación",
            "enum": ["SUCCESS", "ERROR"]
          }
        }
      },
      "UpdateQuizVisibilityDto": {
        "type": "object",
        "properties": {
          "visible": {
            "type": "boolean",
            "description": "true para publicar el cuestionario (visible para los usuarios), false para ocultarlo",
            "example": true
          }
        },
        "required": ["visible"]
      },
      "MarkAllReadResultDto": {
        "type": "object",
        "properties": {
          "updated": {
            "type": "integer",
            "format": "int32",
            "description": "Número de notificaciones que se han marcado como leídas",
            "example": 5
          }
        }
      },
      "AuthorCandidateDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno del usuario. Útil como clave en la lista y para excluir del lado del cliente a los ya seleccionados",
            "example": 42
          },
          "username": {
            "type": ["string", "null"],
            "description": "Nombre público del usuario. Nulo si aún no ha completado su perfil: en ese caso el front debe mostrar solo el email",
            "example": "ada_lovelace"
          },
          "firstName": {
            "type": ["string", "null"],
            "description": "Nombre de pila, si lo ha indicado",
            "example": "Ada"
          },
          "lastName": {
            "type": ["string", "null"],
            "description": "Apellidos, si los ha indicado",
            "example": "Lovelace"
          },
          "email": {
            "type": "string",
            "description": "Email del usuario. Es el valor que se envía en 'authorEmails' al crear o actualizar un PDF",
            "example": "ada@mathtexpedia.es"
          },
          "hasAvatar": {
            "type": "boolean",
            "description": "Si tiene foto de perfil (GET /users/{id}/avatar)"
          }
        }
      },
      "QuizAttemptStatsDto": {
        "type": "object",
        "properties": {
          "totalAttempts": {
            "type": "integer",
            "format": "int32",
            "description": "Número de intentos del usuario autenticado; 0 significa que aún no ha intentado el cuestionario",
            "example": 3
          },
          "completionRate": {
            "type": "number",
            "format": "double",
            "description": "Porcentaje de intentos sin preguntas sin responder",
            "example": 100.0
          },
          "accuracyPercentage": {
            "type": "number",
            "format": "double",
            "description": "Porcentaje de aciertos sobre las preguntas respondidas",
            "example": 75.0
          },
          "averageScore": {
            "type": "number",
            "format": "double",
            "description": "Puntuación media sobre 10",
            "example": 6.5
          },
          "bestScore": {
            "type": "number",
            "format": "double",
            "description": "Mejor puntuación sobre 10 (0 si no hay intentos)",
            "example": 8.0
          }
        }
      },
      "Pageable": {
        "type": "object",
        "properties": {
          "page": { "type": "integer", "format": "int32", "minimum": 0 },
          "size": { "type": "integer", "format": "int32", "minimum": 1 },
          "sort": { "type": "array", "items": { "type": "string" } }
        }
      },
      "LeaderboardEntryDto": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno del usuario; sirve para pedir su foto en GET /users/{id}/avatar"
          },
          "username": {
            "type": ["string", "null"],
            "description": "Nombre público (username) del usuario. Nulo si aún no ha completado su perfil",
            "example": "ada_lovelace"
          },
          "hasAvatar": {
            "type": "boolean",
            "description": "Si el usuario tiene foto de perfil"
          },
          "avatarUpdatedAt": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "Versión de la foto (cuándo se cambió); clave de caché. Nulo si no tiene"
          },
          "bestAdjustedScore": { "type": "number", "format": "double" },
          "rank": { "type": "integer", "format": "int32" }
        }
      },
      "PageLeaderboardEntryDto": {
        "type": "object",
        "properties": {
          "totalPages": { "type": "integer", "format": "int32" },
          "totalElements": { "type": "integer", "format": "int64" },
          "size": { "type": "integer", "format": "int32" },
          "content": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/LeaderboardEntryDto" }
          },
          "number": { "type": "integer", "format": "int32" },
          "sort": { "$ref": "#/components/schemas/SortObject" },
          "pageable": { "$ref": "#/components/schemas/PageableObject" },
          "numberOfElements": { "type": "integer", "format": "int32" },
          "first": { "type": "boolean" },
          "last": { "type": "boolean" },
          "empty": { "type": "boolean" }
        }
      },
      "PageableObject": {
        "type": "object",
        "properties": {
          "unpaged": { "type": "boolean" },
          "offset": { "type": "integer", "format": "int64" },
          "sort": { "$ref": "#/components/schemas/SortObject" },
          "paged": { "type": "boolean" },
          "pageNumber": { "type": "integer", "format": "int32" },
          "pageSize": { "type": "integer", "format": "int32" }
        }
      },
      "SortObject": {
        "type": "object",
        "properties": {
          "unsorted": { "type": "boolean" },
          "empty": { "type": "boolean" },
          "sorted": { "type": "boolean" }
        }
      },
      "QuizAttemptDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador interno del intento de quiz",
            "readOnly": true
          },
          "userId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador del usuario que realizó el intento de quiz",
            "readOnly": true
          },
          "quizId": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador del quiz asociado al intento",
            "example": 1
          },
          "score": {
            "type": "number",
            "format": "double",
            "description": "Puntaje obtenido en el intento de quiz",
            "example": 85.5
          },
          "adjustedScore": {
            "type": "number",
            "format": "double",
            "description": "Puntaje ponderado según el número de intento; es el que cuenta para el leaderboard",
            "example": 6.0
          },
          "attemptNumber": {
            "type": "integer",
            "format": "int32",
            "description": "Número de intento del usuario en este quiz (1 = primer intento)",
            "example": 2
          },
          "totalQuestions": {
            "type": "integer",
            "format": "int32",
            "description": "Número total de preguntas en el intento de quiz",
            "example": 10
          },
          "submittedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Fecha y hora en que se envió el intento de quiz",
            "readOnly": true
          }
        }
      },
      "OptionForAttemptDto": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "format": "int64" },
          "text": { "type": "string" },
          "position": { "type": "integer", "format": "int32" }
        }
      },
      "QuestionForAttemptDto": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "format": "int64" },
          "text": { "type": "string" },
          "type": {
            "type": "string",
            "enum": ["MULTIPLE_CHOICE", "TRUE_FALSE"]
          },
          "position": { "type": "integer", "format": "int32" },
          "options": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/OptionForAttemptDto" }
          }
        }
      },
      "QuizForAttemptDto": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "format": "int64" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "difficulty": {
            "type": "string",
            "enum": ["EASY", "MEDIUM", "HARD"]
          },
          "questions": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/QuestionForAttemptDto" }
          }
        }
      },
      "CurriculumDto": {
        "type": "object",
        "properties": {
          "degree": {
            "$ref": "#/components/schemas/DegreeDto",
            "description": "Grado al que pertenece el plan de estudios"
          },
          "years": {
            "type": "array",
            "description": "Años del plan de estudios en orden. Sin filtro de año incluye todos los años del grado, también los vacíos; con filtro, solo el año pedido",
            "items": { "$ref": "#/components/schemas/CurriculumYearDto" }
          }
        }
      },
      "CurriculumSubjectDto": {
        "type": "object",
        "properties": {
          "subject": {
            "$ref": "#/components/schemas/SubjectDto",
            "description": "Asignatura del plan de estudios"
          },
          "semester": {
            "type": ["integer", "null"],
            "format": "int32",
            "description": "Cuatrimestre (1 o 2). Nulo si la asignatura es anual o no se especifica",
            "example": 1
          }
        }
      },
      "CurriculumYearDto": {
        "type": "object",
        "properties": {
          "year": {
            "type": "integer",
            "format": "int32",
            "description": "Año (curso) del grado",
            "example": 4
          },
          "subjects": {
            "type": "array",
            "description": "Asignaturas de ese año ordenadas por cuatrimestre (las anuales al final) y nombre. Vacía si no hay ninguna",
            "items": { "$ref": "#/components/schemas/CurriculumSubjectDto" }
          }
        }
      },
      "UserProfile": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Email del usuario, extraído del JWT"
          },
          "role": {
            "type": "string",
            "description": "Rol del usuario",
            "enum": ["USER", "ADMIN"]
          },
          "id": { "type": "string" }
        }
      },
      "NotificationDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Identificador de la notificación del usuario (es el que se usa para marcarla como leída o borrarla)",
            "readOnly": true
          },
          "type": {
            "type": "string",
            "description": "Tipo de notificación",
            "enum": [
              "PDF_CREATED",
              "PDF_FILE_UPDATED",
              "QUIZ_PUBLISHED",
              "SUBJECT_CREATED",
              "SUBJECT_UNIT_CREATED",
              "PDF_AUTHOR_ADDED",
              "WELCOME",
              "ANNOUNCEMENT"
            ],
            "example": "PDF_CREATED"
          },
          "category": {
            "type": "string",
            "description": "Categoría de la notificación, útil para elegir el icono",
            "enum": ["CONTENT", "PERSONAL", "SYSTEM"],
            "example": "CONTENT"
          },
          "title": {
            "type": "string",
            "description": "Título corto, ya redactado",
            "example": "Nuevo apunte en Álgebra"
          },
          "message": {
            "type": "string",
            "description": "Mensaje corto, ya redactado",
            "example": "Se ha añadido «Matrices» al tema Matrices y determinantes."
          },
          "link": {
            "type": ["string", "null"],
            "description": "Ruta interna del front a la que llevar al usuario. Solo la traen los avisos manuales; el resto se navega con resourceType y resourceId",
            "example": "/dashboard"
          },
          "resourceType": {
            "type": "string",
            "description": "Tipo del recurso al que apunta (NONE si no apunta a ninguno)",
            "enum": ["PDF", "QUIZ", "SUBJECT", "SUBJECT_UNIT", "NONE"],
            "example": "PDF"
          },
          "resourceId": {
            "type": ["integer", "null"],
            "format": "int64",
            "description": "Id del recurso al que apunta",
            "example": 12
          },
          "subjectId": {
            "type": ["integer", "null"],
            "format": "int64",
            "description": "Id de la asignatura relacionada",
            "example": 3
          },
          "read": {
            "type": "boolean",
            "description": "Si el usuario ya la ha leído"
          },
          "readAt": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "Cuándo la leyó"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Cuándo se generó"
          }
        }
      },
      "PageNotificationDto": {
        "type": "object",
        "properties": {
          "totalPages": { "type": "integer", "format": "int32" },
          "totalElements": { "type": "integer", "format": "int64" },
          "size": { "type": "integer", "format": "int32" },
          "content": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/NotificationDto" }
          },
          "number": { "type": "integer", "format": "int32" },
          "sort": { "$ref": "#/components/schemas/SortObject" },
          "pageable": { "$ref": "#/components/schemas/PageableObject" },
          "numberOfElements": { "type": "integer", "format": "int32" },
          "first": { "type": "boolean" },
          "last": { "type": "boolean" },
          "empty": { "type": "boolean" }
        }
      },
      "UnreadCountDto": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "format": "int64",
            "description": "Número de notificaciones sin leer",
            "example": 3
          }
        }
      },
      "MyPdfVoteDto": {
        "type": "object",
        "properties": {
          "pdfId": {
            "type": "integer",
            "format": "int64",
            "description": "Id del PDF votado",
            "example": 7
          },
          "vote": {
            "type": "string",
            "description": "Voto del usuario autenticado en ese PDF",
            "enum": ["LIKE", "DISLIKE"],
            "example": "DISLIKE"
          }
        }
      },
      "PageQuizAttemptDto": {
        "type": "object",
        "properties": {
          "totalPages": { "type": "integer", "format": "int32" },
          "totalElements": { "type": "integer", "format": "int64" },
          "size": { "type": "integer", "format": "int32" },
          "content": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/QuizAttemptDto" }
          },
          "number": { "type": "integer", "format": "int32" },
          "sort": { "$ref": "#/components/schemas/SortObject" },
          "pageable": { "$ref": "#/components/schemas/PageableObject" },
          "numberOfElements": { "type": "integer", "format": "int32" },
          "first": { "type": "boolean" },
          "last": { "type": "boolean" },
          "empty": { "type": "boolean" }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "name": "bearerAuth",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}