У каждого API есть документация, которую никто не читает от начала до конца. Спецификация OpenAPI может занимать сотни строк с путями, методами, формами запросов и ответов и ресурсами, с которыми они работают. Она точна и полна, и удержать её в голове почти невозможно. Когда вы впервые сталкиваетесь с новым сервисом, вам на самом деле нужна картинка: какие основные ресурсы, какие эндпоинты их затрагивают и как всё это связано между собой?
Эта картинка уже скрыта в спецификации. OpenAPI или похожий документ: это структурированные данные, а значит, инструмент может прочитать его и нарисовать ту форму, которую иначе пришлось бы восстанавливать вручную.
Что уже рассказывает спецификация OpenAPI
В правильно оформленном документе API больше структуры, чем кажется. Из него можно вывести:
- Ресурсы: из схем и сегментов путей (users, orders, products).
- Операции: из методов каждого пути (list, create, update, delete).
- Связи: из ссылок между схемами (Order ссылается на User и Line Items).
- Группировку: из тегов, которые обычно соответствуют реальным модулям сервиса.
Читать это как текст долго. Увидеть это как диаграмму можно мгновенно, и именно на диаграмме наступает момент «а, вот как это устроено».
Как это работает
Это действительно «вставил и готово». Передайте инструменту документ OpenAPI, и он извлечёт ресурсы и связи и разложит их в виде редактируемых фигур. Дальше обычная доводка: сгруппировать по тегам, выделить ключевой ресурс, скрыть эндпоинты, которые для этой конкретной диаграммы только шум.
Спецификация: источник истины для API. Если генерировать диаграмму из неё, картинка и контракт не могут разойтись.
Почему диаграмму архитектуры API лучше выводить, а не рисовать
Можно нарисовать диаграмму API вручную, и она станет неверной, как только кто-то добавит эндпоинт. Вывод из спецификации привязывает картинку к контракту. Когда API меняется, вы генерируете заново, и через несколько секунд диаграмма снова актуальна. Для развивающегося сервиса в этом и разница между документацией, которой доверяют, и документацией, которую тихо игнорируют.
За пределами одного сервиса
Та же идея масштабируется. Если у вас несколько сервисов, у каждого своя спецификация, можно построить карту уровнем выше: какой сервис владеет какими ресурсами и где один вызывает другой. Это та диаграмма, которую ни у кого никогда нет времени поддерживать вручную, и именно она экономит полдня во время инцидента. Пусть её рисуют спецификации, а вы доведёте её до вида, нужного вашей команде.
Хватит читать YAML, чтобы понять сервис. Вставьте спецификацию и читайте картинку.