Swagger: интерактивная документация WB API
Тестирование запросов в браузере, экспорт в Postman и генерация кода
Дата обновления: 03.04.2026
Что такое Swagger
Swagger (OpenAPI) — это формат, в котором представлена интерактивная документация WB API на портале разработчиков. В отличие от основного раздела «Документация», Swagger позволяет не только читать описания методов, но и взаимодействовать с ними: отправлять запросы, видеть ответы, экспериментировать с параметрами — всё прямо в браузере.
Swagger-документация WB API расположена в отдельном разделе портала — «Swagger» в верхнем меню. Каждая категория API имеет свою Swagger-страницу.
Помимо тестирования в браузере, Swagger-спецификацию можно использовать для:
- Импорта в инструменты тестирования API (например, Postman)
- Генерации клиентского кода на разных языках программирования с помощью OpenAPI Generator
- Автоматической генерации типов данных для вашего проекта
Как отправить тестовый запрос через Swagger
Шаг 1. Откройте нужную категорию
В верхнем меню портала наведите курсор на «Swagger» — откроется выпадающий список категорий. Выберите нужную, например «Общее» для проверки подключения.
Шаг 2. Авторизуйтесь
В правой части страницы нажмите кнопку Authorize (с иконкой замка) и вставьте ваш токен WB API. После авторизации все запросы будут содержать этот токен в заголовке Authorization.
Для тестирования рекомендуется использовать тестовый токен и песочницу (sandbox), чтобы не затронуть реальные данные магазина.
Шаг 3. Выберите метод
Методы сгруппированы по тематическим секциям. Раскройте нужную секцию и нажмите на метод — вы увидите его описание, параметры, примеры запроса и ответа.
Шаг 4. Нажмите Try it out
Нажмите кнопку Try it out в правом верхнем углу описания метода. Поля параметров станут редактируемыми — заполните нужные значения или отредактируйте пример в поле Request body.
Шаг 5. Отправьте запрос
Нажмите Execute. Swagger отправит запрос к API и покажет результат ниже.
Как прочитать результат
После нажатия Execute Swagger показывает несколько блоков:
Curl — готовая команда curl для повторения этого же запроса из командной строки. Можно скопировать и выполнить в терминале.
Request URL — полный URL, на который был отправлен запрос. Полезно для отладки — видно, какой именно адрес и параметры использовались.
Server response — основной результат:
| Элемент | Что означает |
|---|---|
| Code | HTTP-код ответа (200 — успех, 400 — ошибка в запросе, 401 — проблема с токеном, 429 — превышен лимит) |
| Response body | Тело ответа в формате JSON — данные, которые вернул API |
| Response headers | Заголовки ответа, включая X-Ratelimit-Remaining (сколько запросов осталось) |
Полный справочник кодов — в статье «Расшифровка кодов ошибок WB API».
Пример: проверка подключения через curl
Swagger генерирует curl-команду автоматически, но вы можете использовать curl и без Swagger. Вот пример проверки подключения:
curl -X GET "https://common-api.wildberries.ru/ping" \
-H "Authorization: Bearer ВАШ_ТОКЕН"
Успешный ответ: "Pong" с кодом 200. Если вернулась ошибка — проверьте токен и категорию.
Как экспортировать спецификацию
Swagger-спецификацию можно скачать для использования в других инструментах. Ссылка на файл swagger.yaml расположена под заголовком категории на Swagger-странице.
Импорт в Postman
- Скачайте файл спецификации по ссылке
swagger.yaml - Откройте Postman → Import → выберите файл
- Postman создаст коллекцию запросов по всем методам категории
- Добавьте токен в настройках авторизации коллекции
Пошаговое руководство — в кейсе «Тестирование WB API с помощью Postman».
Генерация клиентского кода
Используйте инструмент OpenAPI Generator для создания клиентских библиотек на нужном языке программирования (Python, PHP, JavaScript, Go и других). Спецификация WB API соответствует стандарту OpenAPI 3.0 (OAS 3.0).
Ограничения Swagger
При работе со Swagger в браузере учитывайте:
Лимиты запросов действуют так же, как при обычных запросах к API. Если отправлять запросы слишком часто, вы получите ошибку 429. Подробнее — в статье «Лимиты запросов WB API».
Реальные данные. Если вы авторизовались рабочим (не тестовым) токеном, запросы через Swagger будут работать с реальными данными вашего магазина. Запросы на запись (POST, PUT, PATCH, DELETE) изменят реальные данные.
Не все примеры можно выполнить «как есть». Примеры в документации содержат условные значения (например, вымышленные ID товаров). Для успешного запроса замените их на реальные значения из вашего магазина.
Частые проблемы при работе со Swagger
| Проблема | Причина | Решение |
|---|---|---|
| Ответ 401 Unauthorized | Токен не вставлен или истёк | Нажмите Authorize и вставьте актуальный токен |
| Ответ 403 Forbidden | Токен не содержит нужную категорию данных | Создайте токен с категорией, соответствующей этой документации |
| Ответ 429 Too Many Requests | Превышен лимит запросов | Подождите и повторите запрос. Соблюдайте интервал между запросами |
| Кнопка Try it out неактивна | Swagger-страница ещё загружается | Дождитесь полной загрузки страницы |
| Ответ содержит ошибку валидации | Пример содержит условные значения | Замените ID и другие параметры на реальные значения вашего магазина |
Swagger и Документация: в чём разница
На портале WB API есть два раздела с описанием методов — Документация и Swagger. Они дополняют друг друга:
| Документация | Swagger | |
|---|---|---|
| URL | /docs/openapi/... | /swagger/... |
| Назначение | Чтение и изучение методов | Интерактивное тестирование |
| Тестирование запросов | Нет | Да (Try it out → Execute) |
| Навигация | Боковое меню + поиск | Секции с методами |
| Ссылки на гайды | Да (иконки книги) | Нет |
| Скачивание спецификации | Да | Да (swagger.yaml) |
Если нужно понять, как работает метод — используйте Документацию. Если нужно попробовать метод — используйте Swagger.
Подробнее о навигации по документации — в статье «Как пользоваться документацией WB API».
Альтернативные инструменты для тестирования
Помимо Swagger в браузере, для работы с WB API можно использовать:
- Postman — для Windows, macOS, Linux. Импортируйте спецификацию OpenAPI и работайте с коллекцией запросов. Пошаговое руководство — в кейсе «Тестирование WB API с помощью Postman».
- curl — для командной строки. Быстрый способ отправить одиночный запрос. Swagger автоматически генерирует curl-команду для каждого запроса — скопируйте её из результата.
- Песочница WB API — безопасная тестовая среда с искусственными данными. Подробнее — в статье «Тестовый токен и Песочница WB API».