Как вы тестируете API, когда документация — это всего лишь три слова: 'ну, типа, работает'?

О, классика. «Работает» — это не документация, это диагноз. Первое правило: забудь про сваггер, он тут не поможет. Бери curl и начинай дёргать эндпоинты, но не вслепую, а с умом — смотри заголовки, статус-коды, и особенно, что приходит в теле ответа при невалидных данных. Если бэкенд молчит или возвращает 200 на всё подряд — значит, там либо валидации нет, либо она такая же «рабочая», как и доки. Совет из практики: подними перехватчик на уровне сети (mitmproxy или tcpdump) и сравни, что реально уходит с твоего клиента с тем, что ожидает сервер. Часто находишь поля, которые фронт шлёт по привычке, а бэкенд игнорирует — и наоборот. И да, когда совсем тупик, пиши разработчику не «дай доку», а «вот тебе 10 запросов, 9 вернули 500, скажи, где я наврал». Так быстрее найдут баг, чем будут вспоминать, что они там наваяли в пятницу вечером.

О, да, «ну, типа, работает» — это мой любимый вид документации, сразу чувствуешь себя археологом, который раскапывает древний API по обломкам логов! 😄 Я в таких случаях иду по пути «чёрного ящика», но с пристрастием: сначала собираю все реальные запросы через перехватчик (mitmproxy — мой лучший друг), потом запускаю скрипт на Python, который перебирает не только параметры, но и типы данных, null, пустые строки, спецсимволы. И обязательно смотрю, как сервер отвечает на невалидные JSON-схемы — если он молча возвращает 200, это уже сигнал, что валидация «работает» в кавычках. А по поводу разработчиков — я часто прихожу не с просьбой, а с готовым отчётом: «Вот 15 запросов, вот 12 ответов с 500-ми, вот где поля обрезаются, а вот где сервер игнорирует лишние ключи». Так они быстрее понимают, что дело не в моей фантазии, а в их коде. И да, иногда помогает задавать вопросы в стиле «а что будет, если сюда передать отрицательное число?» — это заставляет их открыть код и посмотреть самим, а заодно и доку починить. В общем, главное — не ждать готового, а активно провоцировать систему на раскрытие своих тайн!

Согласен, «археолог» — это точное описание. Только я бы ещё добавил: не забудь про fuzzing, но не на уровне «кинуть рандомные байты», а на уровне бизнес-логики. Типа, если у тебя API принимает ID юзера, попробуй передать туда отрицательное число, ноль и строку «admin». Если бэкенд не отдаёт 422 или 400, а молча возвращает 200 с пустым телом — значит, там не валидация, а декорация. И насчёт подхода с готовым отчётом — это работает, но только если ты покажешь не просто «вот 500-е», а укажешь, где именно контракт ломается. Например, «вот тут ты отдаёшь дату в ISO, а вот тут — в timestamp, и фронт это глотает». Разработчик, который писал это в пятницу вечером, сам не вспомнит, где он накосячил, а вот конкретный дифф на пальцах — вспомнит. И да, если они начнут говорить «это фича» — бери логи и показывай, что фича эта роняет их же прод. Тогда доки появляются сами собой, как по мановению волшебного пенделя.