Схема, сгенерированная из кода, который валидирует
Написанная руками документация API — это обещание про код. Сгенерированная — это его описание.
Один источник, три лица
Каждое тело запроса на этом сервисе описано один раз — валидатором в коде. Из этого единственного определения получаются три вещи: проверка, которую сервер реально выполняет; схемы компонентов в документе OpenAPI по адресу /openapi.json; и схемы входа, которые MCP-инструменты показывают модели.
Поэтому сгенерированный клиент и сервер не могут разойтись во мнении, обязательное поле или нет. Меняется правило — меняются все трое в одном коммите, потому что это один и тот же объект. Руками написан только список путей, и тест роняет сборку, если у задокументированного пути нет роута.
- Направьте генератор на /openapi.json и получите типы для страниц, блоков, патчей и ошибок.
- Или прочитайте его один раз и напишите нужные четыре вызова руками: поверхность достаточно мала, чтобы клиентская библиотека была необязательной.
- Из того же документа собирается действие для кастомного GPT или определение инструмента для вашего агентного фреймворка.
- Перед обновлением загляните в changelog: имена полей стабильны, а всё, что удаляется, объявляется там заранее.
Чего документ вам не скажет
- Какой из десяти шаблонов подходит фотографу. Это вкус, и он живёт в текстовой документации.
- Что короткий путь уникален внутри страницы: ограничение, которое схема выразить не может, и оно приходит ошибкой.
- Что для создания страницы вообще не нужна авторизация. Схемы безопасности описывают, что можно прислать, а не что обязательно.
- Что делать, когда что-то не вышло. Это подсказка при ошибке, и она тоже генерируется из сервера.
Проза для моделей, схема для машин
Схема точна и ничего не говорит о намерении. Модель, читавшая только схему, выдаст валидную страницу, которая почему-то неправильная: одиннадцать ссылок, сгенерированное био, шаблон, воюющий с содержимым. Поэтому один и тот же API задокументирован дважды: схемой для кода и Markdown для того, кому решать, что должно быть на странице.
Оба генерируются, оба лежат по фиксированным адресам, и тест требует, чтобы каждый эндпоинт, каждый код ошибки и каждое имя инструмента упоминались и в прозе. Документация, которая не может разойтись с кодом, — единственная, которую стоит писать для читателя, понимающего буквально.