OpenAPI описывает контракт интерфейса, но разработчику интеграции нужен маршрут действий: авторизоваться, создать ресурс, дождаться результата и обработать отказ. ИИ помогает превратить формальное описание в связный текст. Каждый технический факт должен опираться на контракт или отдельно подтверждённое поведение сервера.
Зафиксируйте источник истины
Сохраните версию OpenAPI-файла и соответствующую версию API. Проверьте разрешение ссылок на схемы, обязательность полей и идентификаторы операций. Перед генерацией попросите модель перечислить пробелы: неописанные ошибки, неизвестную пагинацию, отсутствие ограничений длины. Пропуск в контракте нельзя заполнять удобной догадкой.
Спецификация OpenAPI определяет объекты путей, операций, параметров, ответов и схем безопасности. Используйте версию, объявленную в вашем файле. Не переносите автоматически возможности новой версии в старый контракт и не считайте описание security доказательством фактической настройки сервера.
От справочника к сценарию
- Определите аудиторию: первый запуск или ежедневная работа опытного клиента.
- Выберите минимальный полезный сценарий из нескольких операций.
- Опишите предварительные условия, необходимые права и тестовое окружение.
- Сгенерируйте запросы с синтетическими данными и заглушками секретов.
- Покажите успешный ответ и важные ошибки, которые действительно описаны.
- Проверьте примеры валидатором и, если доступно, на тестовом сервере.
Пример создания задачи
Учебный контракт содержит POST /tasks с обязательным title и необязательным due_at. Ответ 201 возвращает id, title и status. Руководство может показать создание задачи «Проверить отчёт» и сохранение полученного id для следующего запроса. Нельзя добавлять priority или обещать мгновенное выполнение, если таких полей и гарантий нет в источнике.
Для due_at пример должен соответствовать объявленному формату. RFC 3339 описывает распространённое представление временных меток с часовым смещением. Но допустимость отсутствующего значения, сравнение с текущим временем и смысл срока проверяются в конкретном API. Синтаксически допустимая дата ещё не гарантирует допустимую операцию.
Промпт
Используй приложенный OpenAPI как технический источник. Напиши руководство первого запроса и справочник выбранных операций. Сохрани имена, расположение, обязательность и ограничения параметров. Примеры должны соответствовать схемам. Не придумывай коды ошибок, лимиты и гарантии. Пробелы вынеси в «Нужно уточнить». Используй TEST_TOKEN как заглушку.Проверка примеров
Сравните тело запроса со схемой: обязательные поля, типы, перечисления и вложенные объекты. Для ответа проверьте, не представлено ли необязательное поле как всегда существующее. Просмотрите команды: корректны ли кавычки, Content-Type и расположение параметров. Удобный текст с неработающей командой создаёт больше проблем, чем сухая, но точная спецификация.
Не отправляйте демонстрационные POST и DELETE в рабочую среду. Используйте тестовый ресурс с описанной очисткой. Если сервер недоступен, укажите, что примеры проверены только по схеме. В журнале проверки сохраните версию контракта, операцию, обезличенный запрос и фактический ответ, чтобы отличать ошибки текста от отклонений реализации.
Поддержка документации
Разделите автоматически получаемую справочную часть и объяснения сценариев. При изменении контракта сравнивайте обязательность, ограничения, перечисления и ответы. Для интегратора удаление допустимого статуса может быть важнее добавления операции. Храните дату проверки и версию источника возле документации.
Хорошая приёмка: человек, который не писал API, выполняет сценарий по руководству и отмечает места, где пришлось догадываться. Они превращаются в конкретные правки контракта или текста. ИИ можно поручить редактуру, но фактическое поведение подтверждает исполняемый сценарий. Добавьте раздел восстановления после ошибки только после уточнения семантики повторных запросов.
Частые вопросы
Достаточно успешного ответа?
Для интеграции этого мало. Клиенту нужны подтверждённые способы обработки отказа, повторного запроса и отсутствующего ресурса, если они предусмотрены интерфейсом.
Что делать с неполной схемой?
Составить список пробелов и уточнить их у владельца API. Текст не должен незаметно становиться альтернативным, противоречащим контрактом.
Нужны примеры на всех языках?
Начните с проверенного HTTP-примера и языка основной аудитории. Несколько поддерживаемых примеров лучше большого набора, который никто не проверяет при обновлениях.
Гайд подготовлен для Tarasov Code — проекта Ильи Тарасова и TarasovWeb.