OpenAPI в Postman: коллекция запросов из спецификации

Спецификация описывает API, а проверять его тестировщики и разработчики удобнее в Postman. Чтобы не набирать запросы вручную, коллекцию можно собрать из спецификации OpenAPI одним действием: каждая операция станет готовым запросом с параметрами, заголовками и примером тела.

Как получить коллекцию

1. Откройте спецификацию в редакторе OpenAPI (OpenAPI 3.0, 3.1 или Swagger 2.0).
2. Выберите Файл → Преобразовать в → Postman — коллекция (.json), скачать. Скачается файл <название>.postman_collection.json.
3. В Postman нажмите Import и перетащите файл в окно.
4. Откройте коллекцию, вкладку Variables: проверьте адрес сервера baseUrl и впишите токен или ключ доступа.

Что попадает в коллекцию

• Папки — по первому тегу операции; операции без тегов лежат в корне коллекции.
• Названия запросов — из summary, если его нет — из operationId или «метод путь». Устаревшие операции (deprecated) помечены.
• Адрес — {{baseUrl}}/путь. Значение baseUrl — первый адрес из servers с подставленными значениями переменных по умолчанию (для Swagger 2.0 — из schemes, host и basePath).
• Параметры пути — переменные Postman вида :id со значением из примера.
• Параметры запроса и заголовки — все, что объявлены в спецификации. Необязательные добавлены выключенными: включите галочку, если параметр нужен.
• Тело запроса — из example или examples спецификации, а если примера нет — построено по схеме ($ref раскрываются). JSON уходит как raw, формы — как x-www-form-urlencoded или form-data; поля с format: binary становятся полями-файлами.
• Accept и Content-Type — по первому успешному ответу и по типу тела.

Авторизация

Схемы из components.securitySchemes переносятся в настройки авторизации Postman, а секреты — в переменные коллекции, чтобы не хранить их в каждом запросе:

В спецификации	В Postman	Переменные
http, scheme: bearer	Bearer Token	token
http, scheme: basic	Basic Auth	username, password
apiKey в заголовке или query	API Key	apiKey
oauth2, openIdConnect	Bearer Token (токен получите отдельно)	token

Общий раздел security спецификации задаёт авторизацию всей коллекции; запросы её наследуют. Если у операции свой security, он задаётся у запроса, а security: [] превращается в «No Auth».

Пример

Операция спецификации:

/orders:
  post:
    tags: [Заказы]
    summary: Создать заказ
    requestBody:
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Order'}

превращается в запрос «Создать заказ» в папке «Заказы»: POST {{baseUrl}}/orders, заголовок Content-Type: application/json, авторизация Bearer из коллекции и тело по схеме:

{
  "customer": "Иван Петров",
  "total": 1500
}

Ограничения

• Ссылки $ref на другие файлы в скачиваемую коллекцию не раскрываются: после преобразования появится замечание, и значение нужно подставить вручную. Схемы в той же спецификации раскрываются полностью.
• Берётся первый адрес из servers. Другие окружения (тест, прод) удобно завести в Postman как Environments с той же переменной baseUrl.
• Сохранённые примеры ответов и тесты в коллекцию не добавляются.

Вопросы и ответы

Postman умеет импортировать OpenAPI сам — зачем конвертер? Здесь получается обычный файл коллекции v2.1. Его можно положить в репозиторий, отправить коллеге или открыть в Insomnia, Bruno и Hoppscotch, которые умеют импортировать коллекции Postman. Тела запросов уже заполнены примерами, секреты вынесены в переменные.

Можно ли получить команды для терминала? Да: Файл → Преобразовать в → curl — команды (.sh), скачать, см. «OpenAPI в curl».

Спецификация отправляется на сервер? Нет: коллекция собирается в браузере.

Спецификация в Swagger 2.0 — подойдёт? Да, она сначала переводится в OpenAPI 3 автоматически. Перевести её насовсем можно по гайду «Swagger 2.0 в OpenAPI 3».