Схема, згенерована з коду, який валідує
Написана руками документація API — це обіцянка про код. Згенерована — це його опис.
Одне джерело, три обличчя
Кожне тіло запиту на цьому сервісі описане один раз — валідатором у коді. З цього єдиного визначення виходять три речі: перевірка, яку сервер реально виконує; схеми компонентів у документі OpenAPI за адресою /openapi.json; і схеми входу, які MCP-інструменти показують моделі.
Тому згенерований клієнт і сервер не можуть розійтися в думці, обов’язкове поле чи ні. Змінюється правило — змінюються всі троє в одному коміті, бо це той самий об’єкт. Руками написано лише список шляхів, і тест валить збірку, якщо в задокументованого шляху немає роута.
- Спрямуйте генератор на /openapi.json і отримайте типи для сторінок, блоків, патчів і помилок.
- Або прочитайте його один раз і напишіть потрібні чотири виклики руками: поверхня достатньо мала, щоб клієнтська бібліотека була необов’язковою.
- З того самого документа збирається дія для кастомного GPT або визначення інструмента для вашого агентного фреймворку.
- Перед оновленням зазирніть у changelog: імена полів стабільні, а все, що видаляється, оголошується там заздалегідь.
Чого документ вам не скаже
- Який із десяти шаблонів пасує фотографу. Це смак, і він живе в текстовій документації.
- Що короткий шлях унікальний усередині сторінки: обмеження, яке схема виразити не може, і воно приходить помилкою.
- Що для створення сторінки взагалі не потрібна авторизація. Схеми безпеки описують, що можна надіслати, а не що обов’язково.
- Що робити, коли щось не вийшло. Це підказка при помилці, і вона теж генерується із сервера.
Проза для моделей, схема для машин
Схема точна і нічого не каже про намір. Модель, що читала лише схему, видасть валідну сторінку, яка чомусь неправильна: одинадцять посилань, згенероване біо, шаблон, що воює зі вмістом. Тому той самий API задокументовано двічі: схемою для коду і Markdown для того, кому вирішувати, що має бути на сторінці.
Обидва генеруються, обидва лежать за фіксованими адресами, і тест вимагає, щоб кожен ендпоїнт, кожен код помилки і кожне ім’я інструмента згадувалися і в прозі. Документація, яка не може розійтися з кодом, — єдина, яку варто писати для читача, що розуміє буквально.