openapi: 3.0.3
info:
  title: SRAB Учебная Платформа
  version: 1.0.0
  description: >
    HTTP API, реализованное контроллерами из каталога `исх/властелины`.
    Аутентификация выполняется с помощью заголовка `Authorization` вида
    `Basic <имя_пользователя> <пароль>` (без base64).

servers:
  - url: http://localhost:1337

tags:
  - name: Главный
  - name: Пользователи
  - name: Классы
  - name: Уроки
  - name: Ученики
  - name: Учителя

components:
  securitySchemes:
    BasicPassport:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Формат: `Basic <имя_пользователя> <пароль>`. Используется для всех защищённых маршрутов.
  schemas:
    LoginRequest:
      type: object
      required: ["имя пользователя", "пароль"]
      properties:
        "имя пользователя":
          type: string
        "пароль":
          type: string
    CreateTeacherRequest:
      type: object
      required:
        ["имя", "фамилия", "отчество", "образование", "пароль", "повтор пароля"]
      properties:
        "имя":
          type: string
        "фамилия":
          type: string
        "отчество":
          type: string
        "образование":
          type: string
        "пароль":
          type: string
        "повтор пароля":
          type: string
    ChangePasswordRequest:
      type: object
      required: ["новый пароль"]
      properties:
        "новый пароль":
          type: string
    Student:
      type: object
      properties:
        "идентификатор":
          type: integer
          format: int64
        "имя":
          type: string
        "фамилия":
          type: string
        "отчество":
          type: string
        "снилс":
          type: string
        "паспорт":
          type: string
        "наставник":
          type: integer
          format: int64
        "имя пользователя":
          type: string
    StudentListResponse:
      type: object
      properties:
        "ученики":
          type: array
          items:
            $ref: "#/components/schemas/Student"
    CreateStudentResponse:
      type: object
      properties:
        "идентификатор":
          type: integer
          format: int64
        "имя":
          type: string
        "фамилия":
          type: string
        "отчество":
          type: string
        "снилс":
          type: string
        "паспорт":
          type: string
        "учитель":
          type: integer
          format: int64
        "имя пользователя":
          type: string
    Teacher:
      type: object
      properties:
        "идентификатор":
          type: integer
          format: int64
        "имя":
          type: string
        "фамилия":
          type: string
        "отчество":
          type: string
        "имя пользователя":
          type: string
        "образование":
          type: string
    TeacherListResponse:
      type: object
      properties:
        "учителя":
          type: array
          items:
            $ref: "#/components/schemas/Teacher"
    CreateStudentRequest:
      type: object
      required:
        [
          "имя",
          "фамилия",
          "отчество",
          "снилс",
          "паспорт",
          "пароль",
          "повтор пароля",
        ]
      properties:
        "имя":
          type: string
        "фамилия":
          type: string
        "отчество":
          type: string
        "снилс":
          type: string
        "паспорт":
          type: string
        "пароль":
          type: string
        "повтор пароля":
          type: string
    Class:
      type: object
      properties:
        "идентификатор":
          type: integer
          format: int64
        "номер":
          type: integer
        "буква":
          type: string
        "создатель":
          type: integer
          format: int64
    ClassListResponse:
      type: object
      properties:
        "классы":
          type: array
          items:
            $ref: "#/components/schemas/Class"
    CreateClassRequest:
      type: object
      required: ["номер", "буква"]
      properties:
        "номер":
          type: integer
        "буква":
          type: string
          description: Однобуквенное обозначение параллели.
    Lesson:
      type: object
      properties:
        "идентификатор":
          type: integer
          format: int64
        "идентификатор класса":
          type: integer
          format: int64
        "дата":
          type: string
          description: Дата урока (YYYY-MM-DD).
        "название":
          type: string
        "домашнее задание":
          type: string
    LessonListResponse:
      type: object
      properties:
        "уроки":
          type: array
          items:
            $ref: "#/components/schemas/Lesson"
    CreateLessonRequest:
      type: object
      required: []
      properties:
        "дата":
          type: string
          description: Дата урока; альтернативно можно использовать поле «дата урока».
        "дата урока":
          type: string
          description: Альтернативное имя поля «дата».
        "название":
          type: string
          description: Название урока; альтернативно можно использовать поле «тема».
        "тема":
          type: string
          description: Альтернативное имя поля «название».
        "домашнее задание":
          type: string
          description: Текст домашнего задания; альтернативно можно использовать поле «домашка».
        "домашка":
          type: string
          description: Альтернативное имя поля «домашнее задание».
      description: >
        Требует хотя бы одно из полей «дата» или «дата урока», а также «название» или «тема».
        Остальные поля необязательны.
paths:
  /api/:
    get:
      tags: [Главный]
      summary: Проверка здоровья сервиса.
      responses:
        "200":
          description: Успешный ответ.
          content:
            text/plain:
              schema:
                type: string
                example: Привет, мир!

  /api/users:
    post:
      tags: [Пользователи]
      summary: Регистрация учителя (создание пользователя-учителя).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTeacherRequest"
      responses:
        "201":
          description: Учитель создан.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Teacher"
              examples:
                success:
                  summary: Пример созданного учителя
                  value:
                    идентификатор: 1
                    образование: "высшее"
                    имя: "Иван"
                    фамилия: "Иванов"
                    отчество: "Иванович"
                    имя пользователя: "Иван.Иванов"
        "400":
          description: Невалидное тело запроса или пароли не совпадают.
        "500":
          description: Ошибка при обращении к базе.

  /api/users/login:
    post:
      tags: [Пользователи]
      summary: Аутентификация пользователя.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        "200":
          description: Аутентификация прошла успешно.
          content:
            text/plain:
              schema:
                type: string
                example: Рады видеть вас снова :3
        "401":
          description: Неверные учётные данные.
        "500":
          description: Внутренняя ошибка при обращении к базе.

  /api/users/password:
    put:
      tags: [Пользователи]
      summary: Смена пароля авторизованного пользователя.
      security:
        - BasicPassport: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChangePasswordRequest"
      responses:
        "204":
          description: Пароль успешно изменён.
        "400":
          description: Невалидное тело запроса.
        "401":
          description: Неавторизовано (нет или неверный паспорт).
        "422":
          description: Новый пароль отсутствует или пустой.
        "500":
          description: Ошибка при обращении к базе.

  /api/classes:
    get:
      tags: [Классы]
      summary: Список классов, созданных учителем.
      security:
        - BasicPassport: []
      parameters:
        - name: "учитель"
          in: query
          required: false
          description: >
            Идентификатор учителя для фильтрации. Для администраторов параметр обязателен;
            для учителей по умолчанию используется их собственный идентификатор, если
            параметр не указан.
          schema:
            type: integer
            format: int64
          example: 42
      responses:
        "200":
          description: Список доступных классов.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClassListResponse"
        "400":
          description: >
            Некорректные параметры запроса: администраторам необходимо указать параметр
            «учитель», либо передано неверное значение параметра.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Пользователь не является учителем.
        "500":
          description: Ошибка базы данных.
    post:
      tags: [Классы]
      summary: Создание нового класса.
      security:
        - BasicPassport: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateClassRequest"
      responses:
        "201":
          description: Класс создан.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Class"
        "400":
          description: Невалидное тело запроса.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Пользователь не является учителем.
        "422":
          description: Нарушение ограничений БД (дублирование и т.п.).
        "500":
          description: Ошибка базы данных.

  /api/classes/{classId}:
    delete:
      tags: [Классы]
      summary: Удаление класса учителя.
      security:
        - BasicPassport: []
      parameters:
        - name: classId
          in: path
          required: true
          description: Идентификатор класса.
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: Класс удалён.
        "400":
          description: Не указан идентификатор.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Класс не принадлежит учителю.
        "404":
          description: Класс не найден.
        "500":
          description: Ошибка базы данных.

  /api/classes/{classId}/students/{studentId}:
    post:
      tags: [Классы]
      summary: Добавление ученика в класс.
      security:
        - BasicPassport: []
      parameters:
        - name: classId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: studentId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "201":
          description: Ученик добавлен.
        "400":
          description: Недостаточно параметров в маршруте.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Класс не принадлежит учителю.
        "404":
          description: Ученик не найден.
        "422":
          description: Связь уже существует или нарушена целостность.
        "500":
          description: Ошибка базы данных.
    delete:
      tags: [Классы]
      summary: Удаление ученика из класса.
      security:
        - BasicPassport: []
      parameters:
        - name: classId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: studentId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: Ученик удалён из класса.
        "400":
          description: Недостаточно параметров в маршруте.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Класс не принадлежит учителю.
        "404":
          description: Связь ученик-класс не найдена.
        "500":
          description: Ошибка базы данных.

  /api/classes/{classId}/lessons:
    post:
      tags: [Уроки]
      summary: Создание урока.
      security:
        - BasicPassport: []
      parameters:
        - name: classId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateLessonRequest"
      responses:
        "201":
          description: Урок создан.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Lesson"
        "400":
          description: Невалидное тело или отсутствуют обязательные поля.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Класс не принадлежит учителю.
        "422":
          description: Нарушение ограничений при вставке.
        "500":
          description: Ошибка базы данных.
    get:
      tags: [Уроки]
      summary: Список уроков класса.
      security:
        - BasicPassport: []
      parameters:
        - name: classId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: date
          in: query
          required: false
          schema:
            type: string
          description: >
            Дополнительный фильтр по дате (YYYY-MM-DD). Аналогичен маршрутам с сегментом `/date/{date}`.
      responses:
        "200":
          description: Успешный ответ.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LessonListResponse"
        "400":
          description: Не указан идентификатор класса.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Нет доступа к классу.
        "404":
          description: Класс не найден.
        "500":
          description: Ошибка базы данных.

  /api/classes/{classId}/lessons/{date}:
    get:
      tags: [Уроки]
      summary: Список уроков класса за указанную дату.
      security:
        - BasicPassport: []
      parameters:
        - name: classId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: date
          in: path
          required: true
          schema:
            type: string
          description: Дата в формате YYYY-MM-DD.
      responses:
        "200":
          description: Успешный ответ.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LessonListResponse"
        "400":
          description: Недостаточно параметров.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Нет доступа к классу.
        "404":
          description: Класс не найден.
        "500":
          description: Ошибка базы данных.
    delete:
      tags: [Уроки]
      summary: Удаление урока по идентификатору.
      security:
        - BasicPassport: []
      parameters:
        - name: classId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: date
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: Идентификатор урока для удаления.
      responses:
        "204":
          description: Урок удалён.
        "400":
          description: Недостаточно параметров.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Класс не принадлежит учителю.
        "404":
          description: Урок не найден.
        "500":
          description: Ошибка базы данных.

  /api/classes/{classId}/lessons/date/{date}:
    get:
      tags: [Уроки]
      summary: Альтернативный маршрут фильтрации уроков по дате.
      security:
        - BasicPassport: []
      parameters:
        - name: classId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: date
          in: path
          required: true
          schema:
            type: string
            description: Дата в формате YYYY-MM-DD.
      responses:
        "200":
          description: Успешный ответ.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LessonListResponse"
        "400":
          description: Недостаточно параметров.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Нет доступа к классу.
        "404":
          description: Класс не найден.
        "500":
          description: Ошибка базы данных.

  /api/students:
    post:
      tags: [Ученики]
      summary: Создание ученика (только для учителей).
      security:
        - BasicPassport: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateStudentRequest"
      responses:
        "201":
          description: Ученик создан.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateStudentResponse"
        "400":
          description: Невалидное тело запроса или пароли не совпадают.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Пользователь не является учителем.
        "500":
          description: Ошибка базы данных.
    get:
      tags: [Ученики]
      summary: Список учеников по учителю.
      security:
        - BasicPassport: []
      parameters:
        - name: "учитель"
          in: query
          required: false
          description: >
            Идентификатор учителя для фильтрации. Для администраторов параметр обязателен;
            для учителей по умолчанию используется их собственный идентификатор, если
            параметр не указан.
          schema:
            type: integer
            format: int64
          example: 42
      responses:
        "200":
          description: Список учеников.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StudentListResponse"
        "400":
          description: Некорректные параметры запроса.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Пользователь не является учителем.
        "500":
          description: Ошибка базы данных.

  /api/students/{id}:
    get:
      tags: [Ученики]
      summary: Получение ученика по идентификатору.
      security:
        - BasicPassport: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Ученик найден.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Student"
        "400":
          description: Недостаточно параметров.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Пользователь не является учителем.
        "404":
          description: Ученик не найден.
        "500":
          description: Ошибка базы данных.
    delete:
      tags: [Ученики]
      summary: Удаление ученика (только для учителей).
      security:
        - BasicPassport: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: Ученик удалён.
        "400":
          description: Не указан идентификатор.
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Пользователь не является учителем или не наставник указанного ученика.
        "404":
          description: Ученик не найден.
        "500":
          description: Ошибка базы данных.

  /api/teachers:
    get:
      tags: [Учителя]
      summary: Список учителей (только для администраторов).
      security:
        - BasicPassport: []
      parameters:
        - name: "страница"
          in: query
          required: false
          description: Номер страницы (начиная с 1). По умолчанию 1.
          schema:
            type: integer
            minimum: 1
          example: 2
      responses:
        "200":
          description: Успешный ответ.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeacherListResponse"
        "400":
          description: Некорректные параметры запроса (напр., страница < 1).
        "401":
          description: Пользователь не авторизован.
        "403":
          description: Пользователь не является администратором.
        "500":
          description: Ошибка базы данных.