Как перестать писать документацию API вручную и начать жить
Представьте ситуацию: вам досталось легаси-приложение без единой строчки документации, или вы фронтенд-разработчик, которому нужно понять, как работает закрытое мобильное API. Обычно в таких случаях открывают Postman или Proxyman и начинают мучительно прокликивать каждый эндпоинт, копируя JSON-ответы в блокнот. Процесс скучный, долгий и чреват ошибками.
Недавно я наткнулся на небольшую, но крайне полезную утилиту mitmproxy2swagger. Она делает именно то, что написано в названии: берет лог трафика и превращает его в готовую спецификацию OpenAPI 3.0. По сути, вы просто пользуетесь приложением, а документация пишется сама.
Зачем это нужно в реальной работе
Главная ценность инструмента — в автоматизации обратной разработки (reverse engineering). Если у вас есть работающее приложение, но нет описания его бэкенда, mitmproxy2swagger сэкономит вам часы, а то и дни рутины.
Инструмент полезен, когда:
- Нужно быстро набросать Swagger для стороннего API, у которого нет официальной документации.
- Вы пишете интеграционный слой и хотите убедиться, что типы данных в реальности совпадают с тем, что обещал бэкенд-разработчик.
- Требуется создать мок-сервер на основе реальных данных.
Как работает процесс
Весь процесс разбит на два этапа. Это сделано специально, чтобы вы могли контролировать, какие эндпоинты попадут в итоговый файл и как будут выглядеть пути.
Шаг 1. Перехват трафика
Сначала нужно собрать данные. Автор предлагает использовать mitmproxy (а точнее его веб-интерфейс mitmweb). Вы запускаете прокси-сервер, настраиваете клиент (браузер или телефон) на этот прокси и просто совершаете нужные действия в приложении.
Затем сохраняете поток трафика в файл. В mitmweb это делается парой кликов в меню File -> Save.
Шаг 2. Первый проход генерации
Вы запускаете утилиту, указав файл с трафиком и префикс API (например, https://api.example.com/v1).
mitmproxy2swagger -i flow_file -o spec.yaml -p https://api.example.com/v1
После этого в файле spec.yaml появится секция x-path-templates. Это список всех обнаруженных путей, но они пока помечены как ignore:. Это важный момент: здесь вы вручную убираете ignore: у тех ручек, которые вам нужны. Тут же можно настроить переменные пути, превратив /users/123 в /users/{id}.
Шаг 3. Финальная сборка
Запускаете ту же команду второй раз. Теперь утилита видит ваши правки и наполняет спецификацию деталями: структурами запросов, ответов и заголовками. Если добавить флаг --examples, в Swagger упадут еще и реальные примеры данных из трафика.
Не только mitmproxy
Интересно, что проект недавно научился работать с HAR-файлами. Это значит, что для реверс-инжиниринга веб-сайтов вообще не нужно ставить прокси-серверы. Достаточно открыть DevTools в браузере, перейти на вкладку Network, выполнить действия и нажать кнопку Export HAR.
Утилита сама поймет формат файла и обработает его точно так же, как дамп из mitmproxy.
На что стоит обратить внимание
При использовании флага --examples или --headers будьте осторожны. В итоговый файл могут попасть токены авторизации, пароли или персональные данные пользователей. Если вы планируете выкладывать эту документацию в общий доступ, обязательно вычитайте результат на предмет конфиденциальной информации.
Инструмент написан на Python и легко ставится через pip. Если не хочется засорять систему, есть Docker-образ, что удобно для разовых задач.
mitmproxy2swagger — это классический "инструмент одного дела", который справляется с ним отлично. У проекта почти 10 тысяч звезд на GitHub, что для такой узкой ниши говорит о многом.
Кому стоит попробовать:
- Тестировщикам для быстрого создания коллекций запросов.
- Фронтенд-разработчикам, заждавшимся документации от бэкенда.
- Безопасникам для анализа подозрительного трафика приложений.
С чего начать? Попробуйте экспортировать HAR со страницы любого сервиса, которым пользуетесь ежедневно, и посмотрите, как он выглядит "под капотом" через сгенерированный Swagger-интерфейс. Порой там находятся очень любопытные эндпоинты.
