{
    "openapi": "3.0.0",
    "info": {
        "title": "Registro de Notas API",
        "description": "API RESTful para el registro de notas de estudiantes y cursos, utilizando Laravel y JWT.",
        "contact": {
            "email": "soporte@ejemplo.com"
        },
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "http://my-default-host.com",
            "description": "Servidor de la API de Registro de Notas"
        }
    ],
    "paths": {
        "/api/login": {
            "post": {
                "tags": [
                    "Autenticación"
                ],
                "summary": "Iniciar sesión y obtener token JWT",
                "operationId": "222b2625838e3c57e017987f73598fda",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email",
                                    "password"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "example": "user@example.com"
                                    },
                                    "password": {
                                        "type": "string",
                                        "format": "password",
                                        "example": "password"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Token JWT generado exitosamente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "token": {
                                            "description": "JWT Bearer Token",
                                            "type": "string"
                                        },
                                        "type": {
                                            "type": "string",
                                            "example": "bearer"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Credenciales inválidas"
                    }
                }
            }
        },
        "/api/cursos": {
            "get": {
                "tags": [
                    "Cursos"
                ],
                "summary": "6. Listar todos los cursos",
                "description": "Retorna una lista de cursos disponibles, requiere token JWT.",
                "operationId": "getCursosList",
                "responses": {
                    "200": {
                        "description": "Operación exitosa",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/CursoModel"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Cursos"
                ],
                "summary": "7. Crear un nuevo curso",
                "description": "Registra un nuevo curso en la base de datos, requiere token JWT.",
                "operationId": "storeCurso",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CursoRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Curso creado exitosamente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "success"
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Curso creado exitosamente."
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/CursoModel"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "422": {
                        "description": "Error de validación"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/cursos/{id}": {
            "get": {
                "tags": [
                    "Cursos"
                ],
                "summary": "8. Obtener curso por ID",
                "description": "Retorna un curso específico, requiere token JWT.",
                "operationId": "getCursoById",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID del curso",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Operación exitosa",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CursoModel"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "404": {
                        "description": "Recurso no encontrado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Cursos"
                ],
                "summary": "9. Actualizar un curso",
                "description": "Actualiza los datos de un curso existente, requiere token JWT.",
                "operationId": "updateCurso",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID del curso a actualizar",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CursoRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Curso actualizado exitosamente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "success"
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Curso actualizado exitosamente."
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/CursoModel"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "404": {
                        "description": "Recurso no encontrado"
                    },
                    "422": {
                        "description": "Error de validación"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Cursos"
                ],
                "summary": "10. Eliminar un curso",
                "description": "Elimina un curso por su ID, requiere token JWT.",
                "operationId": "deleteCurso",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID del curso a eliminar",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Eliminado exitosamente (No Content)"
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "404": {
                        "description": "Recurso no encontrado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/estudiantes": {
            "get": {
                "tags": [
                    "Estudiantes"
                ],
                "summary": "1. Listar todos los estudiantes",
                "description": "Retorna una lista de estudiantes, requiere token JWT.",
                "operationId": "getEstudiantesList",
                "responses": {
                    "200": {
                        "description": "Operación exitosa",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/EstudianteModel"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Estudiantes"
                ],
                "summary": "2. Crear un nuevo estudiante",
                "description": "Crea un nuevo registro de estudiante, requiere token JWT.",
                "operationId": "storeEstudiante",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/StoreEstudianteRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Estudiante creado exitosamente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EstudianteModel"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "422": {
                        "description": "Error de validación"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/estudiantes/{id}": {
            "get": {
                "tags": [
                    "Estudiantes"
                ],
                "summary": "3. Obtener estudiante por ID",
                "description": "Retorna un estudiante específico, requiere token JWT.",
                "operationId": "getEstudianteById",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID del estudiante",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Operación exitosa",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EstudianteModel"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "404": {
                        "description": "Recurso no encontrado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Estudiantes"
                ],
                "summary": "4. Actualizar un estudiante",
                "description": "Actualiza los datos de un estudiante existente, requiere token JWT.",
                "operationId": "updateEstudiante",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID del estudiante a actualizar",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateEstudianteRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Estudiante actualizado exitosamente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EstudianteModel"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "404": {
                        "description": "Recurso no encontrado"
                    },
                    "422": {
                        "description": "Error de validación"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Estudiantes"
                ],
                "summary": "5. Eliminar un estudiante",
                "description": "Elimina un estudiante por su ID, requiere token JWT.",
                "operationId": "deleteEstudiante",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID del estudiante a eliminar",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Eliminado exitosamente (No Content)"
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "404": {
                        "description": "Recurso no encontrado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/notas": {
            "get": {
                "tags": [
                    "Notas"
                ],
                "summary": "11. Listar todas las notas",
                "description": "Retorna una lista paginada de todas las notas con detalles del estudiante y curso, requiere token JWT.",
                "operationId": "getNotasList",
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Número de elementos por página",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 10
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Operación exitosa",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/Nota"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Notas"
                ],
                "summary": "12. Registrar una nueva nota",
                "description": "Crea un nuevo registro de nota, requiere token JWT.",
                "operationId": "storeNota",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/NotaRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Nota creada exitosamente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Nota registrada"
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/Nota"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "422": {
                        "description": "Error de validación"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/notas/{nota}": {
            "get": {
                "tags": [
                    "Notas"
                ],
                "summary": "13. Obtener nota por ID",
                "description": "Retorna una nota específica, requiere token JWT.",
                "operationId": "getNotaById",
                "parameters": [
                    {
                        "name": "nota",
                        "in": "path",
                        "description": "ID de la nota",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Operación exitosa",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/Nota"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "404": {
                        "description": "Recurso no encontrado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Notas"
                ],
                "summary": "14. Actualizar una nota",
                "description": "Actualiza los datos de una nota existente, requiere token JWT.",
                "operationId": "updateNota",
                "parameters": [
                    {
                        "name": "nota",
                        "in": "path",
                        "description": "ID de la nota a actualizar",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/NotaRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Nota actualizada exitosamente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Nota actualizada"
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/Nota"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "404": {
                        "description": "Recurso no encontrado"
                    },
                    "422": {
                        "description": "Error de validación"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Notas"
                ],
                "summary": "15. Eliminar una nota",
                "description": "Elimina una nota por su ID, requiere token JWT.",
                "operationId": "deleteNota",
                "parameters": [
                    {
                        "name": "nota",
                        "in": "path",
                        "description": "ID de la nota a eliminar",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Eliminado exitosamente",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Nota eliminada"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado"
                    },
                    "404": {
                        "description": "Recurso no encontrado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        }
    },
    "components": {
        "schemas": {
            "CursoRequest": {
                "title": "Datos de Curso",
                "required": [
                    "nombre",
                    "codigo"
                ],
                "properties": {
                    "nombre": {
                        "type": "string",
                        "example": "Matemáticas I"
                    },
                    "codigo": {
                        "type": "string",
                        "example": "MAT101"
                    },
                    "descripcion": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "NotaRequest": {
                "title": "Crear/Actualizar Nota",
                "required": [
                    "estudiante_id",
                    "curso_id",
                    "valor_nota"
                ],
                "properties": {
                    "estudiante_id": {
                        "description": "ID del estudiante.",
                        "type": "integer",
                        "example": "5"
                    },
                    "curso_id": {
                        "description": "ID del curso.",
                        "type": "integer",
                        "example": "2"
                    },
                    "valor_nota": {
                        "description": "Valor de la nota (0-20).",
                        "type": "number",
                        "format": "float",
                        "example": "15.00"
                    },
                    "observacion": {
                        "type": "string",
                        "example": "Asistencia perfecta.",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "StoreCursoRequest": {
                "title": "Crear Curso",
                "description": "Datos necesarios para registrar un nuevo curso.",
                "required": [
                    "nombre"
                ],
                "properties": {
                    "nombre": {
                        "type": "string",
                        "example": "Física I"
                    }
                },
                "type": "object"
            },
            "StoreEstudianteRequest": {
                "title": "Crear Estudiante",
                "required": [
                    "nombre",
                    "codigo_estudiante"
                ],
                "properties": {
                    "nombre": {
                        "type": "string",
                        "example": "María"
                    },
                    "codigo_estudiante": {
                        "description": "Código de matrícula del estudiante",
                        "type": "string",
                        "example": "EST-2025-001"
                    }
                },
                "type": "object"
            },
            "UpdateCursoRequest": {
                "title": "Actualizar Curso",
                "description": "Datos necesarios para modificar un curso.",
                "properties": {
                    "nombre": {
                        "type": "string",
                        "example": "Física II (Corregido)"
                    }
                },
                "type": "object"
            },
            "UpdateEstudianteRequest": {
                "title": "Actualizar Estudiante",
                "description": "Datos necesarios para actualizar un estudiante.",
                "properties": {
                    "nombre": {
                        "type": "string",
                        "example": "Laura Martínez (Actualizado)"
                    },
                    "codigo_estudiante": {
                        "type": "string",
                        "example": "E005"
                    }
                },
                "type": "object"
            },
            "CursoModel": {
                "title": "Modelo de Curso/Materia",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": "true",
                        "example": "1"
                    },
                    "nombre": {
                        "type": "string",
                        "example": "Cálculo Avanzado"
                    },
                    "codigo": {
                        "type": "string",
                        "example": "CAV203"
                    },
                    "descripcion": {
                        "type": "string",
                        "example": "Tópicos especiales en ingeniería.",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "EstudianteModel": {
                "title": "Estudiante",
                "description": "Modelo de datos del estudiante",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": "true",
                        "example": "1"
                    },
                    "nombre": {
                        "type": "string",
                        "example": "Juan Pérez"
                    },
                    "codigo_estudiante": {
                        "type": "string",
                        "example": "C001"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "Nota": {
                "title": "Nota",
                "description": "Registro de nota de un estudiante en un curso específico.",
                "properties": {
                    "id": {
                        "type": "integer",
                        "readOnly": "true",
                        "example": "1"
                    },
                    "estudiante_id": {
                        "type": "integer",
                        "example": "5"
                    },
                    "curso_id": {
                        "type": "integer",
                        "example": "2"
                    },
                    "valor_nota": {
                        "type": "number",
                        "format": "float",
                        "example": "18.50"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            }
        },
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "name": "bearerAuth",
                "in": "header",
                "bearerFormat": "JWT",
                "scheme": "bearer"
            }
        }
    },
    "tags": [
        {
            "name": "Autenticación",
            "description": "Endpoints para login y obtención de token JWT."
        },
        {
            "name": "Estudiantes",
            "description": "Operaciones CRUD para la gestión de estudiantes."
        },
        {
            "name": "Cursos",
            "description": "Operaciones CRUD para la gestión de cursos."
        },
        {
            "name": "Notas",
            "description": "Operaciones CRUD para la gestión de notas de estudiantes."
        }
    ]
}