Zuev/magistr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Добавить REST API

Zuev
2026-02-27 21:15:14 +00:00
parent 6853accde5
commit d16ffcc0d2
1 changed files with 442 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

442
REST-API.md Normal file

@@ -0,0 +1,442 @@
# Справочник REST API: Система расписания университета
Базовый URL: `/api`
---
## 1. Аутентификация (`/api/auth`)
### `POST /api/auth/login` — Вход в систему
**Тело запроса (JSON):**
| Поле | Тип | Обязательное | Описание |
|------------|--------|:------------:|-----------------------------------|
| `username` | String | ✅ | Логин пользователя |
| `password` | String | ✅ | Пароль пользователя |
**Тело ответа (JSON) — `LoginResponse`:**
| Поле | Тип | Присутствие | Описание |
|------------|---------|-------------------------|--------------------------------------------------------------|
| `success` | Boolean | Всегда | `true` при успешном входе, `false` при ошибке |
| `message` | String | Всегда | `"OK"` или сообщение об ошибке |
| `token` | String | Только при `success=true`| UUID-токен сессии |
| `role` | String | Только при `success=true`| Роль: `ADMIN`, `TEACHER` или `STUDENT` |
| `redirect` | String | Только при `success=true`| URL для редиректа: `/admin/`, `/teacher/` или `/student/` |
**Коды ответа:** `200 OK`, `401 Unauthorized`
---
## 2. Пользователи (`/api/users`)
### `GET /api/users` — Список всех пользователей
**Параметры запроса:** Нет
**Тело ответа (JSON) — массив `UserResponse[]`:**
| Поле | Тип | Описание |
|------------|--------|-------------------------------------------|
| `id` | Long | ID пользователя |
| `username` | String | Логин пользователя |
| `role` | String | Роль: `ADMIN`, `TEACHER` или `STUDENT` |
---
### `GET /api/users/teachers` — Список преподавателей
**Параметры запроса:** Нет
**Тело ответа:** Массив `UserResponse[]` (формат аналогичен `/api/users`, но только пользователи с ролью `TEACHER`).
---
### `POST /api/users` — Создание пользователя
**Тело запроса (JSON) — `CreateUserRequest`:**
| Поле | Тип | Обязательное | Валидация | Описание |
|------------|--------|:------------:|------------------------------------|-------------------------------------|
| `username` | String | ✅ | Не пустое, уникальное | Логин нового пользователя |
| `password` | String | ✅ | Минимум 4 символа | Пароль (хэшируется через BCrypt) |
| `role` | String | ✅ | Одно из: `ADMIN`, `TEACHER`, `STUDENT` | Роль пользователя |
**Тело ответа:** `UserResponse` (при успехе)
**Коды ответа:** `200 OK`, `400 Bad Request` (с полем `message`)
---
### `DELETE /api/users/{id}` — Удаление пользователя
**Параметры пути:**
| Параметр | Тип | Обязательное | Описание |
|----------|------|:------------:|-------------------|
| `id` | Long | ✅ | ID пользователя |
**Тело ответа:** `{ "message": "Пользователь удалён" }`
**Коды ответа:** `200 OK`, `404 Not Found`
---
## 3. Аудитории (`/api/classrooms`)
### `GET /api/classrooms` — Список всех аудиторий
**Параметры запроса:** Нет
**Тело ответа (JSON) — массив `ClassroomResponse[]`:**
| Поле | Тип | Описание |
|---------------|------------------|-----------------------------------|
| `id` | Long | ID аудитории |
| `name` | String | Название/номер аудитории |
| `capacity` | Integer | Вместимость |
| `isAvailable` | Boolean | Доступна ли аудитория |
| `equipments` | Equipment[] | Список оборудования (объекты с `id` и `name`) |
---
### `POST /api/classrooms` — Создание аудитории
**Тело запроса (JSON) — `ClassroomRequest`:**
| Поле | Тип | Обязательное | По умолчанию | Валидация | Описание |
|----------------|----------|:------------:|:------------:|------------------------|---------------------------------|
| `name` | String | ✅ | — | Не пустое, уникальное | Название/номер аудитории |
| `capacity` | Integer | ✅ | — | Больше нуля | Вместимость |
| `isAvailable` | Boolean | ❌ | `true` | — | Доступна ли аудитория |
| `equipmentIds` | Long[] | ❌ | `[]` | ID существующего оборудования | Список ID привязанного оборудования |
**Тело ответа:** `ClassroomResponse`
**Коды ответа:** `200 OK`, `400 Bad Request`
---
### `PUT /api/classrooms/{id}` — Обновление аудитории
**Параметры пути:**
| Параметр | Тип | Обязательное | Описание |
|----------|------|:------------:|----------------|
| `id` | Long | ✅ | ID аудитории |
**Тело запроса (JSON) — `ClassroomRequest` (все поля опциональны при обновлении):**
| Поле | Тип | Обязательное | Валидация | Описание |
|----------------|----------|:------------:|--------------------------------|---------------------------------|
| `name` | String | ❌ | Не пустое, уникальное (если передаётся) | Новое название |
| `capacity` | Integer | ❌ | Больше нуля (если передаётся) | Новая вместимость |
| `isAvailable` | Boolean | ❌ | — | Новый статус доступности |
| `equipmentIds` | Long[] | ❌ | — | Новый список ID оборудования (полная замена) |
**Тело ответа:** `ClassroomResponse`
**Коды ответа:** `200 OK`, `400 Bad Request`, `404 Not Found`
---
### `DELETE /api/classrooms/{id}` — Удаление аудитории
**Параметры пути:**
| Параметр | Тип | Обязательное | Описание |
|----------|------|:------------:|----------------|
| `id` | Long | ✅ | ID аудитории |
**Тело ответа:** `{ "message": "Аудитория удалена" }`
**Коды ответа:** `200 OK`, `404 Not Found`
---
## 4. Оборудование (`/api/equipments`)
### `GET /api/equipments` — Список всего оборудования
**Параметры запроса:** Нет
**Тело ответа (JSON) — массив `Equipment[]`:**
| Поле | Тип | Описание |
|--------|--------|--------------------------|
| `id` | Long | ID оборудования |
| `name` | String | Название оборудования |
---
### `POST /api/equipments` — Создание оборудования
**Тело запроса (JSON):**
| Поле | Тип | Обязательное | Валидация | Описание |
|--------|--------|:------------:|-----------------------|-----------------------|
| `name` | String | ✅ | Не пустое, уникальное | Название оборудования |
**Тело ответа:** `Equipment` (объект с `id` и `name`)
**Коды ответа:** `200 OK`, `400 Bad Request`
---
### `DELETE /api/equipments/{id}` — Удаление оборудования
**Параметры пути:**
| Параметр | Тип | Обязательное | Описание |
|----------|------|:------------:|-------------------|
| `id` | Long | ✅ | ID оборудования |
**Тело ответа:** `{ "message": "Оборудование удалено" }`
**Коды ответа:** `200 OK`, `404 Not Found`
---
## 5. Дисциплины (`/api/subjects`)
### `GET /api/subjects` — Список всех дисциплин
**Параметры запроса:** Нет
**Тело ответа (JSON) — массив `Subject[]`:**
| Поле | Тип | Описание |
|--------|--------|----------------------|
| `id` | Long | ID дисциплины |
| `name` | String | Название дисциплины |
---
### `POST /api/subjects` — Создание дисциплины
**Тело запроса (JSON):**
| Поле | Тип | Обязательное | Валидация | Описание |
|--------|--------|:------------:|-----------------------|----------------------|
| `name` | String | ✅ | Не пустое, уникальное | Название дисциплины |
**Тело ответа:** `Subject` (объект с `id` и `name`)
**Коды ответа:** `200 OK`, `400 Bad Request`
---
### `DELETE /api/subjects/{id}` — Удаление дисциплины
**Параметры пути:**
| Параметр | Тип | Обязательное | Описание |
|----------|------|:------------:|------------------|
| `id` | Long | ✅ | ID дисциплины |
**Тело ответа:** `{ "message": "Дисциплина удалена" }`
**Коды ответа:** `200 OK`, `404 Not Found`
---
## 6. Формы обучения (`/api/education-forms`)
### `GET /api/education-forms` — Список форм обучения
**Параметры запроса:** Нет
**Тело ответа (JSON) — массив объектов:**
| Поле | Тип | Описание |
|--------|--------|-------------------------|
| `id` | Long | ID формы обучения |
| `name` | String | Название формы обучения |
---
### `POST /api/education-forms` — Создание формы обучения
**Тело запроса (JSON):**
| Поле | Тип | Обязательное | Валидация | Описание |
|--------|--------|:------------:|-----------------------|-------------------------|
| `name` | String | ✅ | Не пустое, уникальное | Название формы обучения |
**Тело ответа:** `{ "id": Long, "name": String }`
**Коды ответа:** `200 OK`, `400 Bad Request`
---
### `DELETE /api/education-forms/{id}` — Удаление формы обучения
**Параметры пути:**
| Параметр | Тип | Обязательное | Описание |
|----------|------|:------------:|---------------------|
| `id` | Long | ✅ | ID формы обучения |
> [!IMPORTANT]
> Удаление невозможно, если к форме обучения привязаны группы. Сначала необходимо удалить или перепривязать группы.
**Тело ответа:** `{ "message": "Форма обучения удалена" }` или ошибка `{ "message": "Невозможно удалить: есть привязанные группы (N)" }`
**Коды ответа:** `200 OK`, `400 Bad Request`, `404 Not Found`
---
## 7. Группы (`/api/groups`)
### `GET /api/groups` — Список всех групп
**Параметры запроса:** Нет
**Тело ответа (JSON) — массив `GroupResponse[]`:**
| Поле | Тип | Описание |
|---------------------|--------|---------------------------------|
| `id` | Long | ID группы |
| `name` | String | Название группы |
| `educationFormId` | Long | ID формы обучения |
| `educationFormName` | String | Название формы обучения |
---
### `POST /api/groups` — Создание группы
**Тело запроса (JSON) — `CreateGroupRequest`:**
| Поле | Тип | Обязательное | Валидация | Описание |
|-------------------|--------|:------------:|-----------------------------------|-----------------------------------|
| `name` | String | ✅ | Не пустое, уникальное | Название группы |
| `educationFormId` | Long | ✅ | Должен существовать в БД | ID формы обучения |
**Тело ответа:** `GroupResponse`
**Коды ответа:** `200 OK`, `400 Bad Request`
---
### `DELETE /api/groups/{id}` — Удаление группы
**Параметры пути:**
| Параметр | Тип | Обязательное | Описание |
|----------|------|:------------:|-------------|
| `id` | Long | ✅ | ID группы |
**Тело ответа:** `{ "message": "Группа удалена" }`
**Коды ответа:** `200 OK`, `404 Not Found`
---
## 8. Привязка преподавателей к дисциплинам (`/api/teacher-subjects`)
### `GET /api/teacher-subjects` — Список всех привязок
**Параметры запроса:** Нет
**Тело ответа (JSON) — массив `TeacherSubjectResponse[]`:**
| Поле | Тип | Описание |
|---------------|--------|----------------------------|
| `userId` | Long | ID преподавателя |
| `username` | String | Логин преподавателя |
| `subjectId` | Long | ID дисциплины |
| `subjectName` | String | Название дисциплины |
---
### `POST /api/teacher-subjects` — Создание привязки
**Тело запроса (JSON):**
| Поле | Тип | Обязательное | Валидация | Описание |
|-------------|------|:------------:|----------------------------------|----------------------|
| `userId` | Long | ✅ | Преподаватель должен существовать | ID преподавателя |
| `subjectId` | Long | ✅ | Дисциплина должна существовать, привязка уникальна | ID дисциплины |
**Тело ответа:** `{ "message": "Привязка создана" }`
**Коды ответа:** `200 OK`, `400 Bad Request`
---
### `DELETE /api/teacher-subjects` — Удаление привязки
**Тело запроса (JSON):**
| Поле | Тип | Обязательное | Описание |
|-------------|------|:------------:|----------------------|
| `userId` | Long | ✅ | ID преподавателя |
| `subjectId` | Long | ✅ | ID дисциплины |
**Тело ответа:** `{ "message": "Привязка удалена" }`
**Коды ответа:** `200 OK`, `404 Not Found`
---
## 9. Занятия / Расписание (`/api/users/test`)
### `GET /api/users/test` — Список всех занятий
**Параметры запроса:** Нет
**Тело ответа (JSON) — массив `LessonResponse[]`:**
| Поле | Тип | Описание |
|----------------|--------|-------------------------|
| `id` | Long | ID занятия |
| `teacherId` | Long | ID преподавателя |
| `groupId` | Long | ID группы (может быть `null` в ответе) |
| `lessonTypeId` | Long | ID типа занятия / предмета |
| `day` | String | День недели |
| `week` | String | Чётность недели |
| `time` | String | Время занятия |
---
### `POST /api/users/test/create` — Создание занятия
**Тело запроса (JSON) — `CreateLessonRequest`:**
| Поле | Тип | Обязательное | Валидация | Описание |
|----------------|--------|:------------:|----------------|-------------------------------|
| `teacherId` | Long | ✅ | Не `null`, не `0` | ID преподавателя |
| `groupId` | Long | ✅ | Не `null`, не `0` | ID группы |
| `lessonTypeId` | Long | ✅ | Не `null`, не `0` | ID типа занятия / предмета |
| `day` | String | ✅ | Не пустое | День недели |
| `week` | String | ✅ | Не пустое | Чётность недели |
| `time` | String | ✅ | Не пустое | Время занятия |
**Тело ответа:** `LessonResponse` (поля: `lessonTypeId`, `day`, `week`, `time`)
**Коды ответа:** `200 OK`, `400 Bad Request`
---
### `GET /api/users/test/ping` — Проверка доступности
**Параметры запроса:** Нет
**Тело ответа:** `"pong"` (plain text)
**Коды ответа:** `200 OK`
---
## Общий формат ошибок
Все `400 Bad Request` ответы имеют формат:
```json
{
"message": "Текст ошибки на русском языке"
}
```
На `404 Not Found` — возвращается пустое тело.