AI для проектирования REST API: генерация контрактов OpenAPI, валидация и ревью через LLM

Проектирование REST API — это не только выбор между PUT и PATCH. Это десятки ручек, сотни параметров и бесконечное «ой, мы забыли описать ошибку 409». LLM не напишет за вас идеальную спецификацию с первой попытки (спойлер: человек тоже). Но она способна превратить User Story в черновик OpenAPI за минуты, проверить его на соответствие REST-принципам и ткнуть носом в ручки с названиями уровня POST /api/v1/getUserDataByIdActive. Что, согласитесь, уже неплохо.

Если вы только знакомитесь со Swagger и OpenAPI — там разобран фундамент. А здесь — конкретно про AI-ускорение: промпты, pipeline, валидация.

Зачем вообще гонять требования через LLM перед написанием спеки

Стандартный процесс выглядит так: аналитик пишет ТЗ → отдаёт разработчику → разработчик пишет код и попутно придумывает контракт → через месяц тестировщик обнаруживает, что поле userId в одном ответе называется user_id, а в другом — clientId, и никто не помнит почему. Документация API появляется постфактум, если вообще появляется.

LLM меняет порядок: требования → черновик OpenAPI → обсуждение → код. Не «заменили аналитика», а сдвинули контракт на шаг раньше. До того, как разработчик уйдёт в трёхнедельный спринт с непроверенной моделью данных.

Вот как выглядит полный цикл:

graph TD
  A["Требования к API (User Story, ТЗ)"] --> B["LLM-промпт с контекстом"]
  B --> C["Генерация OpenAPI-спецификации"]
  C --> D["Валидация: проверка REST-принципов"]
  D --> E["Проверка названий ручек и методов"]
  E --> F["Финальная OpenAPI-спецификация"]
  C --> G["Обратная связь: доработка промпта"]
  G --> B
  D --> H["Отчёт об ошибках REST-дизайна"]
  E --> I["Рекомендации по неймингу"]
  style A fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style B fill:#f0a500,stroke:#c88400,color:#fff
  style C fill:#7b68ee,stroke:#5a4db2,color:#fff
  style D fill:#50c878,stroke:#3a9a5c,color:#fff
  style E fill:#50c878,stroke:#3a9a5c,color:#fff
  style F fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style G fill:#e0e0e0,stroke:#999,color:#333
  style H fill:#e0e0e0,stroke:#999,color:#333
  style I fill:#e0e0e0,stroke:#999,color:#333

Схема процесса: требования попадают в LLM-промпт, модель генерирует черновик OpenAPI, затем две параллельные ветки валидации — проверка REST-принципов и проверка нейминга ручек. При обнаружении проблем промпт дорабатывается (обратная связь), и цикл повторяется. На выходе — спецификация, которую не стыдно показать на ревью.

Шаг 1: промпт для генерации OpenAPI из требований

Самый частый сценарий: у вас есть User Story в Jira или пара абзацев из ТЗ, и нужно превратить это в спецификацию. Промпт не обязан быть гигантским. Обязательным он должен быть структурированным.

1
Ты — senior backend-разработчик. Сгенерируй OpenAPI 3.0-спецификацию
2
на основе требований ниже.
3

4
Требования:
5
{вставьте текст User Story или фрагмент ТЗ}
6

7
Правила:
8
1. Используй семантически правильные HTTP-методы:
9
   GET для чтения, POST для создания, PUT/PATCH для обновления,
10
   DELETE для удаления.
11
2. Названия ручек — существительные во множественном числе,
12
   kebab-case в path-параметрах.
13
3. Для каждой ручки опиши success-ответ (2xx), типовые ошибки
14
   (400, 404, 409) и схему тела запроса/ответа.
15
4. Поля в camelCase.
16
5. Не выдумывай ручки, которых нет в требованиях.
17
6. Если требование допускает неоднозначную трактовку —
18
   отметь это комментарием # AMBIGUITY в yaml.

На реальных требованиях модель выдаёт спецификацию, где уже прописаны схемы, status codes и даже example-значения. Не идеально, но процентов 70–80 работы сделано. Оставшиеся 20% — как раз то, что отличает Senior-аналитика от «я попросил ChatGPT и скопировал».

Шаг 2: валидация — ищем ошибки до того, как они попадут в код

LLM-сгенерированная спека — это сырой драфт. Следующий промпт — валидатор:

1
Ты — ревьюер API-контрактов. Проверь OpenAPI-спецификацию ниже
2
на соответствие REST-принципам и лучшим практикам.
3

4
Чек-лист проверки:
5
1. Методы соответствуют семантике операции.
6
2. Нет GET-запросов, изменяющих состояние сервера.
7
3. POST не используется для чтения.
8
4. PUT — полное обновление, PATCH — частичное.
9
   Если перепутаны — это ошибка.
10
5. Коды ответов адекватны методу:
11
   POST → 201 Created + Location-заголовок,
12
   PUT/PATCH → 200 или 204 No Content,
13
   DELETE → 204 No Content,
14
   GET → 200 или 404.
15
6. Нет ручек вроде GET /getUsers или POST /createOrder
16
   (глаголы в URL).
17
7. Все поля схем описаны, типы указаны.
18
8. Есть описание для каждого эндпоинта и параметра.
19

20
Формат ответа:
21
- Сначала список ошибок (каждая — номер правила + цитата из спеки).
22
- Затем исправленная версия спеки.

Стоит отметить: модель не проверяет бизнес-логику. Она проверяет форму. Но 80% проблем с API-контрактами — это именно проблемы формы, а не логики. Так что этот шаг закрывает львиную долю багов, которые обычно всплывают на интеграционном тестировании через три спринта.

Шаг 3: нейминг ручек — та самая боль, которую LLM видит лучше человека

Отдельный зверь — названия эндпоинтов. Человек привыкает к своему неймингу и через неделю работы искренне считает POST /api/v1/processUserDataTransaction нормальной ручкой. LLM — нет.

Специфическая проверка:

1
Проверь названия ручек в спецификации ниже на соответствие
2
правилам REST-нейминга. Основные правила:
3
- Существительные, а не глаголы: /users, а не /getUsers.
4
- Множественное число для коллекций: /orders, а не /order.
5
- Иерархия через вложенность: /users/{id}/orders.
6
- Фильтрация, сортировка, пагинация — через query-параметры,
7
  не через path: /users?role=admin, а не /users/admins.
8
- Конечный слеш не ставим.
9
- Никаких /api/getSomethingByFilter.
10

11
Выведи список нарушений в формате:
12
Проблемная ручка | Нарушение | Исправленный вариант

Если тема нейминга для вас новая — держите подробный разбор правил названий ручек. А здесь сфокусируемся на AI-части.

Практический пример: генерация спеки для сущности «Заказ»

Возьмём типовую User Story из e-commerce:

Как пользователь интернет-магазина, я хочу создать заказ, просматривать историю своих заказов, отменять заказ до подтверждения, видеть детали конкретного заказа и отслеживать его статус.

Запускаем промпт из шага 1. На выходе получаем такую структуру (сокращённый вариант того, что генерирует LLM):

1
openapi: 3.0.3
2
info:
3
  title: Order Management API
4
  version: 1.0.0
5
paths:
6
  /orders:
7
    post:
8
      summary: Создать заказ
9
      requestBody:
10
        required: true
11
        content:
12
          application/json:
13
            schema:
14
              $ref: '#/components/schemas/CreateOrderRequest'
15
      responses:
16
        '201':
17
          description: Заказ создан
18
          headers:
19
            Location:
20
              schema:
21
                type: string
22
          content:
23
            application/json:
24
              schema:
25
                $ref: '#/components/schemas/Order'
26
        '400':
27
          description: Некорректные данные заказа
28
    get:
29
      summary: Список заказов пользователя
30
      parameters:
31
        - name: status
32
          in: query
33
          schema:
34
            type: string
35
        - name: page
36
          in: query
37
          schema:
38
            type: integer
39
            default: 1
40
      responses:
41
        '200':
42
          description: Список заказов
43
          content:
44
            application/json:
45
              schema:
46
                type: array
47
                items:
48
                  $ref: '#/components/schemas/Order'
49
  /orders/{orderId}:
50
    get:
51
      summary: Детали заказа
52
      responses:
53
        '200':
54
          description: Детали заказа
55
        '404':
56
          description: Заказ не найден
57
    delete:
58
      summary: Отменить заказ
59
      responses:
60
        '204':
61
          description: Заказ отменён
62
        '409':
63
          description: Заказ уже нельзя отменить

Примечательно, что модель сама догадалась добавить Location-заголовок к 201, пагинацию через query-параметры и 409 Conflict для бизнес-ограничения «нельзя отменить подтверждённый заказ». Ни в одном промпте я этого явно не просил. LLM достраивает REST-контракт из контекста задачи — и делает это на удивление адекватно.

Дальше прогоняем валидацию. Ошибки типовые: в delete-ручке для отмены нет схемы ошибки 409 (модель указала код, но без content), и в GET /orders не хватает описания для query-параметра status. Пять минут правок — и спека готова к ревью.

Ограничения: что LLM пока не умеет

На первый взгляд — магия. Но есть четыре принципиальных ограничения, о которых надо знать заранее:

LLM не понимает бизнес-контекст. Она не знает, что «отмена заказа» в вашей компании — это не DELETE, а POST /orders/{id}/cancel с компенсационным документом в теле ответа. Бизнес-логику диктуете вы.
Спеки для сложных микросервисных ландшафтов модель генерирует изолированно. Для каждого сервиса — отдельно. Стыковку контрактов между сервисами придётся проверять вручную или писать отдельный оркестрирующий промпт.
Аутентификация и авторизация. Модель может описать securitySchemes (Bearer, OAuth2), но расставить permission на уровне ручек (кто имеет доступ к /admin/orders vs /my/orders) — это по-прежнему задача архитектора.
Версионирование API. LLM не предложит вам стратегию /v1 vs /v2, не предупредит о breaking changes и не спроектирует обратную совместимость. Это зона архитектурных решений, а не генерации.

Оговорка: это не серебряная пуля. LLM — инструмент ускорения, а не замена инженерного мышления. Если вы ждали кнопку «сделать хорошо» — её нет. Но кнопка «сделать 80% работы за 5 минут» — вот она, и грех её не нажимать.

Когда имеет смысл использовать этот подход

Ситуация	Подход	Экономия
Новый микросервис с 5–15 ручками	Генерация спеки из User Story	1–2 часа вместо 4–6
Рефакторинг старого API без документации	Генерация из кода + валидация	3–4 часа вместо 1–2 дней
Ревью контракта перед ревью кода	Валидация и нейминг-проверка	Экономия на переписывании после ревью
Микросервисный ландшафт из 5+ сервисов	Генерация посегментно + ручная стыковка	~30% времени проектирования
Быстрый прототип / PoC	Генерация без глубокой валидации	5 минут вместо часа

Важно: если у вас простая CRUD-ручка на три эндпоинта — не надо гонять LLM. Напишите руками. Инструмент должен решать проблему, а не создавать новую — ощущение, что «процесс стал AI-powered, значит круто» без реальной экономии времени.

Заключение

LLM не проектирует API за вас. Она делает черновую работу: переводит текст требований в структурированный контракт, проверяет его на грубые ошибки и не ленится перечитать названия всех ручек, даже если их сорок шесть. Человек же делает то, что человеку удаётся лучше всего: принимает решения.

И да, если вы никогда не писали промпт для генерации OpenAPI — попробуйте. Прямо сейчас. Возьмите любую User Story из бэклога и скормите модели. Результат, скорее всего, будет не идеальным. Но вы удивитесь, сколько рутины модель берёт на себя с первой же попытки.

P.S. Если модель сгенерировала POST /api/v1/getOrderHistory — вы забыли добавить правила нейминга в промпт. Не вините инструмент, вините промпт.