311 lines
14 KiB
Markdown
311 lines
14 KiB
Markdown
# REST API (Swagger-Style)
|
||
|
||
## Общая информация
|
||
- **Базовый URL**: `http://0.0.0.0:8080/api/v1`
|
||
- **Форматы**: все конечные точки принимают и возвращают `application/json`, если не указан иной `Content-Type`.
|
||
- **Часовой формат**: даты/время сериализуются в `ISO_LOCAL_DATE_TIME`, например `2024-05-12T13:45:00`.
|
||
- **JWT-аутентификация**: приватные маршруты располагаются под `/api/v1/admin/**` и требуют заголовок `Authorization: Bearer <token>` из `POST /admin/login`.
|
||
- **Ошибки**: при валидационных/авторизационных ошибках сервер возвращает код `4xx` с телом `{"error": "описание"}`.
|
||
|
||
## Базовые схемы
|
||
| Схема | Описание |
|
||
| --- | --- |
|
||
| **Page<T>** | Обёртка пагинации: `items` (список сущностей `T`), `total` (общее количество), `limit` (число элементов на странице), `offset` (смещение). |
|
||
| **ServiceCategoryDTO** | `{ id: number, name: string, slug: string }`. |
|
||
| **ServiceDTO** | `{ id, title, slug, description, priceFrom: number\|null, imageUrl: string\|null, status: "PUBLISHED"\|"DRAFT"\|"ARCHIVED", category: ServiceCategoryDTO\|null, createdAt, updatedAt }`. |
|
||
| **NewsDTO** | `{ id, title, slug, summary, content, status: "draft"\|"published"\|"archived", imageUrl: string\|null, publishedAt: string\|null }`. |
|
||
| **LeadDTO** | `{ id, fullName, email, phone: string\|null, createdAt }`. |
|
||
| **AdminDTO** | `{ id, username, createdAt }`. |
|
||
|
||
---
|
||
|
||
## Администраторы и аутентификация
|
||
| Метод | Путь | Требуется JWT | Описание |
|
||
| --- | --- | --- | --- |
|
||
| POST | `/admin/login` | Нет | Получение JWT токена. |
|
||
| GET | `/admin/password_hash` | Нет | Вспомогательный эндпойнт для генерации bcrypt-хэша. |
|
||
| GET | `/admin` | Да | Получить профиль текущего администратора. |
|
||
| POST | `/admin` | Да | Создать нового администратора. |
|
||
| PUT | `/admin/{id}/password` | Да | Сменить пароль администратора. |
|
||
| DELETE | `/admin/{id}` | Да | Удалить администратора. |
|
||
|
||
### POST /api/v1/admin/login
|
||
**Тело запроса**
|
||
|
||
| Поле | Тип | Обязательно | Примечание |
|
||
| --- | --- | --- | --- |
|
||
| `username` | string | да | Мин. 3 символа (`[A-Za-z0-9_.-]`). |
|
||
| `password` | string | да | Мин. 8 символов. |
|
||
|
||
**Ответ 200**
|
||
|
||
| Поле | Тип | Примечание |
|
||
| --- | --- | --- |
|
||
| `id` | number | Идентификатор администратора. |
|
||
| `username` | string | Введённое имя. |
|
||
| `token` | string | JWT access token. |
|
||
| `tokenType` | string | Всегда `Bearer`. |
|
||
| `expiresInMinutes` | number | Время жизни токена (минуты). |
|
||
|
||
Пример:
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"username": "admin",
|
||
"token": "eyJhbGciOi...",
|
||
"tokenType": "Bearer",
|
||
"expiresInMinutes": 60
|
||
}
|
||
```
|
||
|
||
### GET /api/v1/admin/password_hash
|
||
**Query-параметры**
|
||
|
||
| Параметр | Тип | Обязательно | Описание |
|
||
| --- | --- | --- | --- |
|
||
| `password` | string | нет | Исходный пароль. По умолчанию `admin123`. |
|
||
|
||
**Ответ 200**: `{ "pass": "<bcrypt-hash>" }`.
|
||
|
||
### GET /api/v1/admin
|
||
Возвращает `AdminDTO` текущего пользователя по subject токена.
|
||
|
||
### POST /api/v1/admin
|
||
**Тело запроса** – `AdminRegisterRequest`:
|
||
|
||
| Поле | Тип | Обязательно | Примечание |
|
||
| --- | --- | --- | --- |
|
||
| `username` | string | да | Уникальное имя (регулярное выражение как при логине). |
|
||
| `password` | string | да | Мин. 8 символов. |
|
||
|
||
**Ответ 201** – `AdminRegisterResponse`:
|
||
|
||
| Поле | Тип |
|
||
| --- | --- |
|
||
| `id` | number |
|
||
| `username` | string |
|
||
|
||
### PUT /api/v1/admin/{id}/password
|
||
**Параметры пути**: `id` – numeric ID.
|
||
|
||
**Тело запроса** – `ChangePasswordRequest`:
|
||
|
||
| Поле | Тип | Обязательно | Примечание |
|
||
| --- | --- | --- | --- |
|
||
| `currentPassword` | string | да | Текущий пароль (проверяется через bcrypt). |
|
||
| `newPassword` | string | да | Новый пароль, минимум 8 символов. |
|
||
|
||
**Ответ 200**: `{ "updated": true }`.
|
||
|
||
### DELETE /api/v1/admin/{id}
|
||
Удаляет администратора. Ответ `200 OK`: `{ "deleted": true }`.
|
||
|
||
---
|
||
|
||
## Лиды (заявки)
|
||
| Метод | Путь | JWT | Описание |
|
||
| --- | --- | --- | --- |
|
||
| POST | `/leads` | Нет | Оставить заявку. |
|
||
| GET | `/admin/leads` | Да | Список лидов с фильтром. |
|
||
| GET | `/admin/leads/{id}` | Да | Получить лид по ID. |
|
||
| DELETE | `/admin/leads/{id}` | Да | Удалить лид. |
|
||
|
||
### POST /api/v1/leads
|
||
**Тело запроса** – `LeadCreateRequest`:
|
||
|
||
| Поле | Тип | Обязательно | Примечание |
|
||
| --- | --- | --- | --- |
|
||
| `fullName` | string | да | Имя клиента. |
|
||
| `email` | string | да | Проверяется регуляркой `^[\\w.+-]+@[\\w.-]+\\.[A-Za-z]{2,}$`. |
|
||
| `phone` | string | нет | Любой формат, сохраняется как строка. |
|
||
|
||
**Ответ 201**: `{ "id": 42 }`.
|
||
|
||
### GET /api/v1/admin/leads
|
||
**Query-параметры**
|
||
|
||
| Имя | Тип | По умолчанию | Описание |
|
||
| --- | --- | --- | --- |
|
||
| `limit` | integer | 50 | Размер страницы. |
|
||
| `page` | integer | 1 | Должна быть ≥ 1, иначе `400`. |
|
||
| `q` | string | null | Поиск по `fullName`, `email`, `phone`. |
|
||
|
||
**Ответ 200**: `Page<LeadDTO>`.
|
||
Пример элемента: `{ "id": 7, "fullName": "Иван Иванов", "email": "ivan@example.com", "phone": "+79001234567", "createdAt": "2024-05-05T10:34:00" }`.
|
||
|
||
### GET /api/v1/admin/leads/{id}
|
||
Параметр `id` (long). Ответ – `LeadDTO`.
|
||
|
||
### DELETE /api/v1/admin/leads/{id}
|
||
Ответ `{ "deleted": true }`.
|
||
|
||
---
|
||
|
||
## Новости
|
||
| Метод | Путь | JWT | Описание |
|
||
| --- | --- | --- | --- |
|
||
| GET | `/news` | Нет | Пагинированный список опубликованных новостей. |
|
||
| GET | `/news/{slug}` | Нет | Получение новости по `slug`. |
|
||
| GET | `/admin/news` | Да | Список всех новостей. |
|
||
| POST | `/admin/news` | Да | Создать новость. |
|
||
| PUT | `/admin/news/{slug}` | Да | Обновить новость. |
|
||
| POST | `/admin/news/{slug}/publish` | Да | Публикация новости. |
|
||
| DELETE | `/admin/news/{slug}` | Да | Удалить новость. |
|
||
|
||
### GET /api/v1/news
|
||
**Query-параметры**: `limit` (default 20), `page` (default 1, ≥1).
|
||
**Ответ**: `Page<NewsDTO>`, где `items` отсортированы по `publishedAt` у опубликованных записей.
|
||
|
||
### GET /api/v1/news/{slug}
|
||
Возвращает `NewsDTO` опубликованной новости (если slug неактивен — `404`).
|
||
|
||
### GET /api/v1/admin/news
|
||
**Query-параметры**: `limit` (50), `page` (1, ≥1).
|
||
**Ответ**: `Page<NewsDTO>` (включая черновики).
|
||
|
||
### POST /api/v1/admin/news
|
||
**Тело запроса** – `NewsCreate`:
|
||
|
||
| Поле | Тип | Обязательно | Примечание |
|
||
| --- | --- | --- | --- |
|
||
| `title` | string | да | Заголовок. |
|
||
| `slug` | string | да | Уникальный slug (валидация – на уровне базы). |
|
||
| `summary` | string | да | Краткое описание. |
|
||
| `content` | string | да | Полный текст (HTML/Markdown). |
|
||
| `status` | string | нет | `draft` (по умолчанию) \| `published` \| `archived`. |
|
||
| `imageUrl` | string | нет | Ссылка на обложку. |
|
||
|
||
**Ответ**: `{ "id": <number> }`.
|
||
|
||
### PUT /api/v1/admin/news/{slug}
|
||
**Тело запроса** – `NewsUpdateRequest` (все поля опциональны, как в `NewsCreate`). Ответ `{ "updated": true }`.
|
||
|
||
### POST /api/v1/admin/news/{slug}/publish
|
||
Без тела. Устанавливает `status = "published"`, `publishedAt = now`. Ответ `{ "published": true }`.
|
||
|
||
### DELETE /api/v1/admin/news/{slug}
|
||
Ответ `{ "deleted": true }`.
|
||
|
||
---
|
||
|
||
## Категории услуг
|
||
| Метод | Путь | JWT | Описание |
|
||
| --- | --- | --- | --- |
|
||
| GET | `/service-categories` | Нет | Публичный список категорий. |
|
||
| GET | `/service-categories/{slug}` | Нет | Получить категорию по slug. |
|
||
| GET | `/admin/service-categories` | Да | Пагинация категорий. |
|
||
| POST | `/admin/service-categories` | Да | Создать категорию. |
|
||
| PUT | `/admin/service-categories/{id}` | Да | Обновить категорию. |
|
||
| DELETE | `/admin/service-categories/{id}` | Да | Удалить категорию. |
|
||
|
||
### GET /api/v1/service-categories
|
||
Возвращает массив `ServiceCategoryDTO`.
|
||
|
||
### GET /api/v1/service-categories/{slug}
|
||
Ответ – `ServiceCategoryDTO`.
|
||
|
||
### GET /api/v1/admin/service-categories
|
||
**Query-параметры**: `limit` (100), `offset` (0).
|
||
Ответ: список `ServiceCategoryDTO` (без обёртки).
|
||
|
||
### POST /api/v1/admin/service-categories
|
||
**Тело запроса** – `CategoryCreateRequest` (`name`, `slug` – обязательные). Ответ `{ "id": <number> }`.
|
||
|
||
### PUT /api/v1/admin/service-categories/{id}
|
||
Тело – `CategoryUpdateRequest` (оба поля опциональны). Ответ `{ "updated": true }`.
|
||
|
||
### DELETE /api/v1/admin/service-categories/{id}
|
||
Ответ `{ "deleted": true }`.
|
||
|
||
---
|
||
|
||
## Услуги
|
||
| Метод | Путь | JWT | Описание |
|
||
| --- | --- | --- | --- |
|
||
| GET | `/services` | Нет | Список опубликованных услуг с фильтрами. |
|
||
| GET | `/services/{slug}` | Нет | Одна услуга по slug. |
|
||
| GET | `/admin/services` | Да | Список всех услуг. |
|
||
| POST | `/admin/services` | Да | Создать услугу. |
|
||
| PUT | `/admin/services/{id}` | Да | Обновить услугу. |
|
||
| PUT | `/admin/services/{id}/status` | Да | Изменить статус. |
|
||
| DELETE | `/admin/services/{id}` | Да | Удалить услугу. |
|
||
|
||
### GET /api/v1/services
|
||
**Query-параметры**
|
||
|
||
| Имя | Тип | По умолчанию | Описание |
|
||
| --- | --- | --- | --- |
|
||
| `limit` | integer | 20 | Размер страницы. |
|
||
| `page` | integer | 1 | ≥ 1. |
|
||
| `q` | string | null | Поиск по `title` и `description` (case-insensitive). |
|
||
| `category` | string | null | `slug` категории. |
|
||
| `minPrice` | number | null | Минимальная цена (decimal). |
|
||
| `maxPrice` | number | null | Максимальная цена (decimal). |
|
||
|
||
**Ответ**: `Page<ServiceDTO>`.
|
||
Пример элемента:
|
||
```json
|
||
{
|
||
"id": 10,
|
||
"title": "Разработка мобильного приложения",
|
||
"slug": "mobile-dev",
|
||
"description": "Полный цикл разработки",
|
||
"priceFrom": 150000.0,
|
||
"imageUrl": "https://cdn.example/app.jpg",
|
||
"status": "PUBLISHED",
|
||
"category": { "id": 2, "name": "Разработка", "slug": "development" },
|
||
"createdAt": "2024-04-01T09:15:00",
|
||
"updatedAt": "2024-05-05T12:00:00"
|
||
}
|
||
```
|
||
|
||
### GET /api/v1/services/{slug}
|
||
Ответ – `ServiceDTO` (включая `category`). Ошибка `404`, если slug не найден или услуга скрыта.
|
||
|
||
### GET /api/v1/admin/services
|
||
**Query-параметры**
|
||
|
||
| Имя | Тип | По умолчанию | Описание |
|
||
| --- | --- | --- | --- |
|
||
| `limit` | integer | 50 | Размер страницы. |
|
||
| `page` | integer | 1 | ≥ 1. |
|
||
| `q` | string | null | Фильтр по названию/описанию. |
|
||
| `status` | string | null | `PUBLISHED` \| `DRAFT` \| `ARCHIVED`. |
|
||
|
||
Ответ: `Page<ServiceDTO>` (включая черновики).
|
||
|
||
### POST /api/v1/admin/services
|
||
**Тело запроса** – `ServiceCreateRequest`:
|
||
|
||
| Поле | Тип | Обязательно | Примечание |
|
||
| --- | --- | --- | --- |
|
||
| `title` | string | да | Название услуги. |
|
||
| `slug` | string | да | Уникальный slug (`^[a-z0-9-]{3,}$`). |
|
||
| `description` | string | да | Детальное описание. |
|
||
| `priceFrom` | string | нет | Десятичное число, например `"1499.99"`. |
|
||
| `imageUrl` | string | нет | URL изображения. |
|
||
| `status` | string | нет | По умолчанию `PUBLISHED`. |
|
||
| `categoryId` | number | нет | ID существующей категории. |
|
||
|
||
**Ответ 201**: `{ "id": <number> }`.
|
||
|
||
### PUT /api/v1/admin/services/{id}
|
||
Тело – `ServiceUpdateRequest` (все поля опциональны, формат как в `ServiceCreateRequest`). Ответ `{ "updated": true }`.
|
||
|
||
### PUT /api/v1/admin/services/{id}/status
|
||
**Тело запроса** – `StatusRequest` с полем `status` (`PUBLISHED`\|`DRAFT`\|`ARCHIVED`). Ответ `{ "updated": true }`.
|
||
|
||
### DELETE /api/v1/admin/services/{id}
|
||
Ответ `{ "deleted": true }`.
|
||
|
||
---
|
||
|
||
## Пример структуры Page
|
||
```json
|
||
{
|
||
"items": [ /* сущности */ ],
|
||
"total": 125,
|
||
"limit": 20,
|
||
"offset": 0
|
||
}
|
||
``` |