Автоматизация описания REST API контрактов — это когда люди так устали писать документа...
Автоматизация описания REST API контрактов — это когда люди так устали писать документацию руками, что решили: «Пусть за нас это сделает зоопарк из Confluence, Postman и Python». Сначала появляется Confluence. — Мы сделаем живую базу знаний по API! Рисуют структуру, шаблоны, странички. Через месяц половина страниц помечена «устарело», вторая половина — «в работе», третья — «черновик, не смотреть». Но выглядит красиво: дерево слева, диаграммки, таблички. Документации много, правды мало. Потом врывается Postman. — Зачем описывать руками? Мы будем генерить коллекции, а из них — спеки, а из них — страницы! В итоге рождается сложная литургия: 1. кто‑то когда‑то честно обновляет коллекцию; 2. скрипт на Python ночами героически превращает это в JSON, потом в OpenAPI, потом в Markdown; 3. ещё один скрипт тащит это в Confluence через API. Утром менеджер открывает страницу и говорит: — Вау, у нас всё задокументировано автоматически! В этот момент разработчик тихо шепчет: — Только коллекция была обновлена полгода назад, а половина эндпоинтов живёт в другом сервисе… но кого волнует. Python тут вообще как хирург в поликлинике: ему дают три куска данных разного качества, просят «склей, чтобы выглядело профессионально», и удивляются, когда он честно склеивает тот хаос, который вы ему скормили. Любимый эффект: Система меняется каждый спринт, Postman коллекции кто‑то «дообновит потом», скрипт честно генерит доку, Confluence гордо показывает свежую дату обновления. Фактически у вас: • контракт в коде один, • в Postman — второй, • в Confluence — третий, зато всё «автоматизировано», «по процессу» и «с пайплайном». В какой‑то момент честный джун спрашивает: — А где правда? Ответ опытного синьора: — Правда там же, где всегда — в том микросервисе, к которому никто не хочет лезть, потому что страшно. Всё остальное — красивый фронт для людей, которые верят в «автогенерацию документации» так же, как мы когда‑то верили в «один источник правды».