2026-10-26

Swagger и Postman: в чём разница и как работать с ними вместе

Коротко: Swagger описывает API, Postman его вызывает. Под Swagger понимают спецификацию OpenAPI (файл, где перечислены все запросы сервиса, их параметры и ответы) и инструменты вокруг неё, прежде всего Swagger UI, страницу документации с кнопкой Try it out. Postman же API-клиент: в нём отправляют запросы, хранят коллекции, окружения, историю и тесты. Они не конкурируют: из спецификации как раз делают коллекцию для клиента.

Этот вопрос часто задают на собеседованиях QA и аналитиков. Ответ «один описывает, другой отправляет» почти верный: в Swagger UI тоже можно отправить запрос.

Swagger и OpenAPI: одно и то же?#

Почти. С 2016 года формат называется OpenAPI Specification, а имя Swagger осталось за инструментами компании SmartBear. Сам Swagger появился в 2011 году как формат описания REST API, а в конце 2015-го его передали в OpenAPI Initiative под крылом Linux Foundation. Старую версию формата можно встретить под двумя названиями: Swagger 2.0 и OpenAPI 2.0.

Инструменты SmartBear с этим именем:

• Swagger UI рисует из спецификации интерактивную документацию;
• Swagger Editor помогает писать спецификацию и сразу видеть результат;
• Swagger Codegen генерирует по ней клиентский и серверный код.

Поэтому «у нас есть Swagger» в команде обычно означает: где-то лежит файл openapi.json или openapi.yaml, а по адресу вроде /swagger открывается страница с документацией.

Можно ли тестировать API в Swagger UI#

Можно, но вручную и по одному запросу. Swagger UI хорош как витрина. На одной странице видны все методы, их параметры и примеры ответов. Нажмите Try it out, заполните поля, Execute, и запрос уйдёт на сервер прямо из браузера. Для токена есть кнопка Authorize.

Для разовой проверки этого хватает. Если же работать с API каждый день, ограничения всплывают быстро:

• Ничего не сохраняется. Нельзя сохранить запрос с заполненными параметрами и вернуться к нему завтра. Истории ответов тоже нет. По умолчанию даже токен из Authorize пропадает после перезагрузки страницы.
• Нет окружений. Чтобы проверить тот же запрос на стенде и на проде, нужна другая страница или другая спецификация.
• Нет цепочек и тестов. Нельзя взять токен из ответа на логин и подставить его в следующий запрос или проверить, что в ответе нужное поле.
• Запрос отправляет браузер. Если документация открыта не с того же адреса, что API, сервер должен разрешать такие запросы (CORS). Иначе Try it out упадёт с ошибкой, хотя сам API работает.

Это умеют API-клиенты: Postman, Insomnia, Bruno, Tetiva.

Чем Swagger отличается от Postman: таблица#

Как они работают вместе#

В типичной команде цепочка такая:

1. Бэкенд описывает API в коде, а фреймворк сам собирает из этого спецификацию.
2. Swagger UI показывает её всем как документацию.
3. QA, фронтенд и аналитики импортируют спецификацию в API-клиент и работают уже там: сохраняют запросы, заводят окружения, пишут проверки.
4. Когда API меняется, спецификацию импортируют заново.

Адреса и поля не приходится перепечатывать из документации, поэтому и опечаток меньше. Учтите, что повторный импорт обычно создаёт новую коллекцию рядом со старой: свои проверки и заполненные параметры придётся перенести вручную.

Где взять файл спецификации#

Ссылка на файл обычно стоит прямо на странице Swagger UI, под заголовком. Если её нет, вот где файл лежит по умолчанию в популярных фреймворках:

Адреса могут быть изменены в настройках проекта. Тогда проще спросить у бэкенда или открыть вкладку «Сеть» в инструментах разработчика на странице документации: Swagger UI загружает спецификацию отдельным запросом, и её адрес будет в списке.

Как импортировать Swagger в Postman или другой клиент#

Postman

1. Нажмите Import: кнопка есть в боковой панели или в блоке Use resources or import на странице рабочего пространства.
2. Перетащите файл openapi.json или openapi.yaml либо вставьте ссылку на него. Для пробы подойдёт публичная спецификация Petstore.
3. Postman узнает OpenAPI и предложит импортировать его как коллекцию или как спецификацию с коллекцией, для пробы хватит коллекции. В настройках импорта запросы можно разложить по папкам по тегам, а не по путям.
4. Нажмите Import. Адрес сервера окажется в переменной коллекции baseUrl, а параметры пути станут переменными вида :petId. У Petstore адрес в спецификации относительный (/api/v3), поэтому в baseUrl допишите хост: https://petstore3.swagger.io/api/v3.

Tetiva

1. Нажмите «Импорт из файла…» над деревом коллекций и выберите openapi.json или openapi.yaml. Подходят OpenAPI 3.0 и 3.1 и Swagger 2.0. Если спецификация доступна только по ссылке, сначала сохраните её на диск.
2. Окно подтверждения покажет, сколько получится папок, запросов и примеров, какое окружение добавится и на какие хосты пойдут запросы, а ещё что не перенесётся. Если адрес сервера в спецификации относительный, как у Petstore, окно предупредит об этом и попросит вписать полный адрес в baseUrl.
3. Нажмите «Импортировать». Окружение с адресом сервера сразу станет активным: впишите токен, и запрос можно отправлять.

Что происходит при импорте:

• первый тег операции становится папкой, а операция запросом с именем из summary или operationId;
• параметры пути вроде {petId} превращаются в переменные {{petId}};
• тело запроса берётся из примера в спецификации или собирается по схеме;
• авторизация берётся из securitySchemes: Bearer, Basic, Digest, API key, OAuth 2.0;
• примеры ответов сохраняются рядом с запросами;
• появляется окружение с именем API: в нём адрес первого сервера, параметры пути и пустые места под токены.

Не переносятся внешние $ref, callbacks, webhooks и links, полный список есть в документации по импорту.

Как проверить, что API отвечает по спецификации#

Спецификация и сервер со временем расходятся: поле переименовали, число стало строкой, а документацию обновить забыли. В Swagger UI пример из документации и настоящий ответ видны на одной странице, но сравнивать их приходится глазами.

Чтобы сравнить ответ в Tetiva, отправьте запрос, нажмите стрелку рядом с кнопкой «Сравнить» в строке статуса и выберите пример из спецификации: он называется по коду ответа, например 200 OK. Пример встанет рядом с текущим ответом, расхождения подсветятся. «Нормализовать JSON» включено сразу: ключи отсортированы, а метки времени не учитываются.

Если у успешного JSON-ответа в спецификации нет примера, Tetiva соберёт его по схеме. Значения в таком примере условные, поэтому смотрите на имена полей и типы. Подробнее о сравнении в документации по ответам.

А наоборот, из коллекции в спецификацию?#

Иногда спецификации нет, а коллекция есть, и хочется получить из неё документацию. Можно, но получится черновик: в коллекции есть запросы и примеры ответов, но нет схем и обязательных полей, их придётся дописывать руками. Поэтому спецификацию надёжнее генерировать из кода сервиса: так она не разойдётся с тем, что API делает на самом деле. Tetiva такую выгрузку не делает, коллекции она экспортирует только в формат Postman v2.1.

Что ещё спрашивают на собеседовании#

• Можно ли тестировать API в Swagger? Вручную и по одному запросу можно: Try it out, затем Execute. Сохранённых запросов, окружений и автоматических проверок там нет.
• Зачем Postman, если есть Swagger UI? Чтобы хранить запросы, переключаться между стендами, связывать запросы в цепочки и проверять ответы.
• Swagger и OpenAPI одно и то же? OpenAPI называется сам формат спецификации, а под Swagger чаще всего имеют в виду инструменты для него: Swagger UI, Editor, Codegen.
• Как перенести Swagger в Postman? Импортировать файл спецификации кнопкой Import, и Postman соберёт из него коллекцию.
• Что первично, спецификация или коллекция? Спецификация. Сначала API описывают в ней, а коллекцию запросов потом собирают из неё.

Что выбрать#

• Понять, что умеет API: откройте Swagger UI.
• Один раз дёрнуть метод: хватит Try it out.
• Работать с API каждый день, проверять на нескольких стендах, хранить запросы и делиться ими с командой: импортируйте спецификацию в API-клиент.
• Спецификация поменялась: импортируйте её заново, а не правьте запросы руками.
• Проверить, что API отвечает по спецификации: сравните ответ с примером из неё, в Tetiva это делает кнопка «Сравнить».