813 lines
26 KiB
YAML
813 lines
26 KiB
YAML
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: Ошибка базы данных.
|