Как обновить документацию API по изменениям кода
После изменения API документация часто отстает в мелочах: обязательное поле стало необязательным, код ошибки переименовали, а пример запроса все еще показывает старую схему. ИИ способен найти вероятные расхождения между diff, спецификацией и тестами, если источники четко заданы. Это руководство помогает обновить документацию так, чтобы каждое изменение опиралось на проверяемое поведение, а не на догадку модели.
Что подготовить
Что делать
Зафиксируйте базовую и целевую версии
Укажите ветку до изменения, commit с изменением, версию API и целевые клиенты. Разделите публичные контракты, внутренние интерфейсы и неподтвержденные экспериментальные endpoints. Если изменение обслуживает несколько версий, определите, для какой версии обновляется текст. Не формируйте справку только из файла спецификации, если она генерируется или модифицируется в другом этапе сборки.
Результат: Область сравнения и источник фактической версии.Соберите источники истины
Сопоставьте код обработчика, схему запроса и ответа, тесты, миграционные примечания и текущую документацию. Для спорного поведения попросите владельца API подтвердить контракт. Тест показывает конкретный случай, но может не покрывать все допустимые значения. Комментарий в коде полезен, но не всегда отражает то, что реально принимает сервер. Пометьте каждый источник его ролью и датой.
Результат: Набор источников с указанием, что именно они подтверждают.Составьте карту изменений
Из diff выделите новые и удаленные поля, изменение типов, ограничений, значения по умолчанию, ошибок, авторизации, пагинации и идемпотентности. Для каждого пункта укажите маршрут, метод, версию и совместимость. Помечайте изменения как совместимые, потенциально ломающие или требующие решения владельца. Не просите ИИ писать готовый релизный текст, пока список не подтвержден разработчиком.
Результат: Таблица изменений до редактуры документации.Перепишите схемы и примеры
Обновите заголовки, типы, required-поля, nullable, ограничения длины и форматы дат. Проверьте пример на соответствие текущему тестовому запросу или OpenAPI-схеме. Удалите секреты и реальные идентификаторы из логов. Пример должен показывать успешный ответ и, если это важно, один частый отказ. Не копируйте ответ среды разработки, если там случайно присутствуют внутренние поля.
Результат: Согласованная схема и обезличенные примеры.Опишите миграцию и переходный период
Для измененного контракта объясните, что увидит старый клиент, с какой даты работает новая версия, как обнаружить использование прежнего поля и когда оно удаляется. Если переход не подтвержден календарем или политикой, не придумывайте сроки. Добавьте шаги проверки для потребителя и способ отката, если он поддерживается. Breaking change должен быть видимым в кратком резюме, а не спрятан в примечании.
Результат: Инструкция перехода с подтвержденными датами и ограничениями.Проверьте связи и локальные ссылки
Пройдите ссылку от overview до метода, схемы, ошибки и migration guide. Убедитесь, что якоря работают, используемые имена совпадают и страницы не описывают разные версии как одну. Если документация локализована, создайте список строк, где термин или статус версии изменился, и направьте перевод на проверку. Машинный перевод может ускорить черновик, но не подтверждает семантику контракта.
Результат: Маршрут читателя без устаревших переходов.Сверьте документацию с исполняемыми тестами
Запустите существующую проверку примеров, линтер спецификации или contract tests, если они есть в проекте. Не придумывайте, что такие тесты выполнены, если вы только составили текст. Если автоматической проверки нет, подготовьте короткий контрольный список для рецензента: валидность примера, совпадение схемы, код ошибки, права доступа, версия и дата. Результат проверки храните рядом с изменением.
Результат: Подтверждение, что обновленные примеры проверены предусмотренным способом.Опубликуйте изменения с трассировкой
В PR свяжите участок документации с изменением кода и соответствующим тестом. Попросите владельца API проверить поведение, а редактора - понятность для пользователя. Укажите известные пробелы и нерешенные вопросы. После публикации проверьте конечный URL документа и соответствие версии. Если код меняется повторно, не оставляйте ранее сгенерированный черновик как источник истины.
Результат: Документационное изменение, связанное с подтвержденным кодовым diff.Шаблон задания для ИИ
Сравни diff API, текущую спецификацию, тесты и существующую страницу документации. Сначала выдай только матрицу: изменение, маршрут/поле, подтверждающий источник, влияние на клиента, неизвестные условия. Не пиши, что тесты выполнены, если в данных есть только код или план. После подтверждения матрицы предложи конкретные правки текста и примера. Сохраняй имена полей дословно, не придумывай сроки депрекации, права, лимиты и коды ошибок.
Проверка перед применением
Что чаще всего портит результат
Принимать подсказку за подтвержденный факт
Оставьте ссылку на исходную запись и поручите владельцу данных подтвердить существенное утверждение.
Скрывать исключения и неопределенность
Выведите неизвестные поля и случаи без надежного основания в отдельную очередь ручной проверки.
Короткие ответы
Можно ли сразу автоматизировать принятие решения?
Начните с подготовки черновика или очереди проверки. Автоматическое действие допустимо только после проверки ошибок, прав доступа и процедуры отмены.
Как оценить, полезен ли процесс?
Сравните время обработки, долю исправлений, число пропусков и серьезность ошибок на сопоставимых случаях. Зафиксируйте базовый уровень до запуска.
Коротко
Документация API надежна, когда читатель может пройти от описания до подтвержденного контракта и рабочего примера. ИИ ускоряет разбор diff, но владелец интерфейса подтверждает поведение, а разработчик проверяет исполняемые примеры. Сохраняйте версии и связи с кодом, чтобы следующий релиз не превратил полезный черновик в устаревшую инструкцию. Отдельно сверяйте потоковые ответы, вебхуки и асинхронные операции: их жизненный цикл нельзя описать одним примером успешного запроса. Уточните, какие значения возвращаются до завершения задачи, как клиент получает финальный статус и что происходит при повторном callback. Для пагинации проверьте курсор и поведение при изменении набора между страницами. Для авторизации укажите требуемые scope и пример ответа при нехватке полномочий, если эти сведения подтверждены контрактом. Такие детали часто остаются в коде и тестах, но критичны интеграторам. Согласуйте, какая документация считается генерируемой, а какая редактируется вручную, иначе следующее обновление спецификации может затереть исправленное пояснение. Сформируйте небольшую приемочную выборку из типичных и граничных сценариев: нормальный запрос, отсутствующий параметр, недостаточные права, повтор операции и устаревшая версия. Для каждого примера укажите источник ожидаемого поведения - схему, контрактный тест или согласованное решение команды. После публикации проверьте, что ссылки из changelog ведут именно на затронутые разделы и что старые примеры не остались в поисковой выдаче внутри документации. Такой контроль ловит несогласованность между новой спецификацией и прежним пояснением.