init here

openapi/srab.yaml

@@ -0,0 +1,812 @@
+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: Ошибка базы данных.