API Reference

Этот раздел демонстрирует, как документация API встраивается в общий пайплайн разработки по методологии Docs-as-Code.

OpenAPI-спецификация

Полная спецификация доступна в файле api/openapi.yaml. Она написана в формате OpenAPI 3.0 — индустриальном стандарте описания REST API.

Преимущества подхода

Единый источник правды — спецификация хранится в репозитории и версионируется через Git.
Автогенерация — по спецификации можно автоматически сгенерировать клиентские библиотеки, серверные заглушки (mock) и интерактивную документацию (Swagger UI, Redoc).
Ревью через pull requests — изменения API проходят проверку перед публикацией.
Проверка в CI/CD — спецификацию можно валидировать автоматически (например, спектром spectral).

Конечные точки

Метод	Путь	Описание
`GET`	`/health`	Проверка работоспособности сервиса
`GET`	`/documents`	Получить список документов
`POST`	`/documents`	Создать новый документ
`GET`	`/documents/{id}`	Получить документ по идентификатору
`DELETE`	`/documents/{id}`	Удалить документ

Модель данных

Document

Основная сущность — документ:

Поле	Тип	Описание
`id`	`uuid`	Уникальный идентификатор
`title`	`string`	Заголовок документа
`content`	`string`	Содержимое документа
`status`	`enum`	Статус: `draft`, `review`, `published`
`createdAt`	`date-time`	Дата создания
`updatedAt`	`date-time`	Дата последнего обновления

Пример запроса

Получить список опубликованных документов:

curl -X GET "https://api.profdefence.ru/v1/documents?limit=10" \
  -H "Accept: application/json"

Ответ:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Быстрый старт",
  "content": "Пример документации...",
  "status": "published",
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-01-20T12:30:00Z"
}

Что дальше?

Руководство по интеграции — подключение внешних сервисов.
Руководство по настройке — конфигурация системы.