Прощай, Swagger UI - почему Scalar стал моим фаворитом для документации API

Вы когда-нибудь задумывались, почему в 2025 году мы всё ещё смотрим на интерфейсы документации, которые выглядят как привет из начала десятых? Стандартный Swagger UI надёжен, как кирпич, но ровно так же неповоротлив и скучен. Когда я впервые наткнулся на Scalar, меня зацепило не только то, что он выглядит «по-человечески», но и то, как глубоко ребята продумали работу с OpenAPI.

Что это вообще такое

Scalar — это опенсорсная платформа, которая берёт ваш файл OpenAPI (или Swagger) и превращает его в интерактивный справочник. Но это только верхушка айсберга. Проект объединяет в себе генератор документации и полноценный API-клиент. По сути, это попытка скрестить эстетику современных SaaS-сервисов с мощностью Postman, причём сделать это максимально легковесно.

Если вам надоело объяснять фронтенд-разработчикам, как именно вызвать эндпоинт, или вы сами путаетесь в параметрах запроса — этот инструмент может сильно упростить жизнь.

Чем он лучше привычных инструментов

Я выделил несколько моментов, которые заставили меня пересмотреть свои взгляды на оформление доков.

Дизайн, за который не стыдно

Первое, что бросается в глаза — интерфейс. Он чистый, быстрый и поддерживает тёмную тему «из коробки» (привет всем, кто выжигал глаза белым фоном Swagger ночью). В левой части удобная навигация, в центре — описание методов, а справа — живой редактор запросов и примеры кода.

Встроенный клиент для тестов

В отличие от многих генераторов, где кнопка «Try it out» выглядит как костыль, здесь встроен полноценный API-клиент. Он поддерживает переменные окружения, динамические параметры и сохраняет историю. Можно скачать десктопное приложение для Windows, MacOS или Linux, если вам привычнее работать вне браузера.

Примеры кода на любой вкус

Scalar генерирует сниппеты для десятков языков и фреймворков. Хотите вызвать API через fetch в JavaScript, requests в Python или HttpClient в .NET? Просто переключите вкладку. Это экономит кучу времени при интеграции.

Как запустить за пять минут

Самое приятное — порог входа. Чтобы развернуть красивую документацию, вам не нужно настраивать сложные пайплайны. Достаточно обычного HTML-файла:

<!doctype html>
<html>
  <head>
    <title>My Awesome API</title>
    <meta charset="utf-8" />
  </head>
  <body>
    <div id="app"></div>
    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
    <script>
      Scalar.createApiReference('#app', {
        url: 'https://your-api.com/openapi.json',
      })
    </script>
  </body>
</html>

Просто подставьте ссылку на ваш JSON-файл со спецификацией, и всё готово. Если вы используете популярные фреймворки, то всё ещё проще. У проекта есть готовые интеграции для FastAPI, NestJS, Go, Rust, Elixir и даже Django. Список поддерживаемых технологий в репозитории действительно впечатляет — там больше 30 позиций.

Практическая польза

Для кого Scalar станет спасением?

Во-первых, для команд, которые пишут публичные API. Хорошая документация — это лицо продукта. Если разработчик видит удобный интерфейс с готовыми примерами кода, он с гораздо большей вероятностью выберет ваш сервис.

Во-вторых, для внутренних микросервисов. Когда у вас в компании десятки сервисов, искать актуальный эндпоинт в разрозненных доках — та ещё пытка. Scalar позволяет собрать всё в одном месте. У них даже есть функция «Watch Mode», которая синхронизирует документацию с кодом в реальном времени.

Стоит ли переходить

Проект активно развивается, и за ним стоит живое сообщество (более 14 тысяч звёзд на GitHub говорят сами за себя). Из минусов я бы отметил, что для очень специфических кастомизаций всё равно придётся лезть в конфиги, а документация по плагинам местами могла бы быть подробнее.

Тем не менее, если вы ищете замену стандартному Swagger UI или хотите переехать с платных инструментов вроде ReadMe.io, Scalar — отличный кандидат. Он бесплатный, открытый и делает ровно то, что обещает: превращает скучные спецификации в инструмент, которым приятно пользоваться.

Попробовать демо можно прямо в браузере на их сайте, чтобы понять, подходит ли вам такой стиль работы. Лично я свой выбор сделал.