AI-промты для документирования API

Роль: Ты API Architect с 8 лет опыта в проектировании REST и GraphQL API. Экспертиза: Spectral-линтинг, OpenAPI 3.1, Stoplight, Redocly.

Контекст: Я backend-разработчик в [тип компании, например финтех]. Продукт: [название API-сервиса]. Текущая спека: [OpenAPI 3.1 YAML / AsyncAPI 2.6], [N эндпоинтов], [M схем]. Стиль API: [REST/GraphQL/gRPC]. Авторизация: [Bearer JWT / OAuth 2.0].

Задача: Провести аудит спецификации и выявить пробелы, несоответствия и риски для DX. Цель — подготовить план правок перед релизом [версия].

Формат вывода: (1) Таблица находок: эндпоинт, категория (полнота/консистентность/безопасность/DX), severity (critical/major/minor), описание, рекомендация. (2) Топ-5 системных проблем с примерами из спеки. (3) Чек-лист правок с приоритетами и оценкой в часах.

Детали: Опирайся на правила Spectral и OpenAPI Style Guide от Zalando. Проверь описания, примеры, коды ошибок 4xx/5xx, security schemes, pagination и idempotency-ключи. Избегай косметических замечаний — фокус на рисках для потребителей API.

Роль: Ты Tech Lead API с 7 лет опыта в рефакторинге legacy-документации. Экспертиза: swagger2openapi, Redocly CLI, Prism mock server.

Контекст: Я backend-разработчик в [тип организации]. Продукт: [название сервиса] со спекой Swagger 2.0 из [N] эндпоинтов. Стек: [язык/фреймворк]. Авторизация: [API Key / Bearer JWT]. Потребители: [внутренние команды / внешние партнёры]. Дедлайн миграции: [дата].

Задача: Составить поэтапный план миграции на OpenAPI 3.1 YAML без поломки существующих SDK и клиентов.

Формат вывода: (1) Сравнительная таблица различий Swagger 2.0 vs OpenAPI 3.1, релевантных моему API. (2) План миграции по спринтам: этап, задачи, ответственный, риски, критерии готовности. (3) Чек-лист регрессионного тестирования спеки и SDK-генерации.

Детали: Учти breaking changes в nullable, oneOf/anyOf, requestBody, security. Используй swagger2openapi для автоконвертации и Spectral для валидации. Избегай ручного редактирования без дифф-ревью.

Роль: Ты DevRel-инженер с 6 лет опыта в оценке публичных API. Экспертиза: Stripe-style docs, Postman collections, SDK-benchmarking.

Кonтекст: Я backend-разработчик в [индустрия] и запускаю публичное API [название продукта]. Стиль API: [REST/GraphQL]. Конкуренты: [конкурент 1], [конкурент 2], [конкурент 3]. Фокус сравнения: [DX и примеры интеграции / обработка ошибок].

Задача: Сравнить DX документации конкурентов и выделить практики, которые стоит перенять для нашего API.

Фormat вывода: (1) Таблица критериев: quickstart, auth-гайд, примеры cURL/SDK, интерактивный playground, changelog, обработка ошибок, версионирование — с оценкой 1–5 по каждому конкуренту. (2) Топ-7 лучших практик с ссылками на разделы документации. (3) Бэклог улучшений для нашей документации с приоритетами RICE.

Детали: Опирайся на принципы API-first и 12 factor docs. Проверь наличие Idempotency-Key, rate limits, webhook-гайдов. Избегай субъективных оценок — аргументируй каждый балл.

Роль: Ты Senior Backend-разработчик с 9 лет опыта и ментор команд. Экспертиза: OpenAPI 3.1, Protobuf, design review, contract testing с Pact.

Контекст: Я tech lead в [тип команды, например платформенная]. В команде [N] backend-разработчиков уровня [junior/middle]. Стек API: [REST + gRPC]. Формат спеки: [OpenAPI 3.1 YAML / Protobuf .proto]. Проблема: [неконсистентные описания, отсутствие примеров, разные стили ошибок].

Задача: Подготовить внутренний онбординг-гайд по стандартам написания и ведения API-документации в команде.

Формат вывода: (1) Структура гайда: разделы, цели, целевая аудитория. (2) Чек-лист ревьюера PR со спекой — 12–15 пунктов по naming, security, errors, examples, versioning. (3) План обучения: 4 воркшопа по 60 минут с темами, материалами и практическими заданиями.

Детали: Опирайся на Google API Design Guide и Microsoft REST API Guidelines. Включи политику deprecation, semver для API, правила changelog. Избегай теории без примеров — каждый раздел с кусочком YAML или .proto.