postman2swagger

Docker-образ для генерации Swagger/OpenAPI документации из Postman-коллекции.

Скачивает коллекцию из Postman API и конвертирует в swagger.json или swagger.yaml.

Использование

docker run --rm \
    -v /path/to/output:/docs \
    miroff/postman2swagger:latest \
    "<POSTMAN_API_KEY>" \
    "<POSTMAN_COLLECTION_ID>" \
    "/docs/swagger.json"

Выходной формат определяется расширением файла: .json или .yaml/.yml.

Внедрение в проект

1. Добавить переменные окружения

В .env (или CI/CD secrets):

POSTMAN_API_KEY=your-postman-api-key
POSTMAN_API_EXTERNAL_COLLECTION_ID=your-collection-id

POSTMAN_API_KEY — Postman → аватарка (правый верхний угол) → Settings → API keys → Generate API Key.

POSTMAN_API_EXTERNAL_COLLECTION_ID — открыть коллекцию в Postman Web, в URL будет:

https://app.getpostman.com/collection/12345678-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Длинный UUID после последнего слэша — это и есть Collection ID.
Альтернативно: правый клик на коллекции → View documentation → ID в URL страницы.

2. Добавить цель в Makefile проекта

doc-swagger: ## Generate Swagger documentation
    docker run --rm \
        -v $(shell pwd)/docs/swagger:/docs \
        miroff/postman2swagger:latest \
        "$(POSTMAN_API_KEY)" \
        "$(POSTMAN_API_EXTERNAL_COLLECTION_ID)" \
        "/docs/swagger.json"

3. Создать конфиг (опционально)

Положи swagger.config.yaml рядом с swagger.json (в той же папке, которая монтируется как /docs):

servers:
  - url: https://api.yourproject.com
    description: Production

replace:
  "{{host}}": api.yourproject.com
  "{{alert.intake.key}}": your-key-here
  "{{alert.intake.header.timestamp}}": "1234567890"

• servers — полностью перезаписывает список серверов из коллекции
• replace — глобальные замены строк по всему документу (пути, описания, примеры)

Конфиг подхватывается автоматически — менять команду в Makefile не нужно.

Переменные коллекции Postman → поля OpenAPI

Переменные коллекции с префиксом openapi. напрямую перезаписывают поля в итоговом документе. Часть после префикса — это путь в JSON.

Примеры:

Переменная в Postman	Что меняет в OpenAPI
openapi.info.version	info.version
openapi.info.title	info.title
openapi.info.x-foo	info.x-foo (любое поле)

Как добавить в Postman: открыть коллекцию → вкладка Variables → добавить переменную с нужным именем и значением.

Приоритет: config.replace перекрывает переменные коллекции, если оба задают одно и то же поле.

Дата последнего обновления

Конвертер автоматически добавляет в info['x-updated'] дату и время генерации в формате YYYY-MM-DD HH:MM UTC. Это поле не является частью стандарта OpenAPI — мы вставляем его сами.

В сгенерированном index.html эта дата отображается под заголовком:

Updated: 2026-05-26 10:34 UTC

index.html перезаписывается при каждой генерации.

4. Добавить директорию в .gitignore (опционально)

Если генерируемый файл не нужно коммитить:

docs/swagger/swagger.json

Обновление образа

Образ версионируется тегами. Рекомендуется указывать конкретную версию вместо latest:

miroff/postman2swagger:1.0.0

Разработка

# Собрать образ локально (текущая платформа)
make build TAG=dev

# Собрать и опубликовать для linux/amd64 и linux/arm64 (Mac + CI)
make build-multiplatform TAG=1.0.3

# Опубликовать уже собранный образ
make push TAG=1.0.3

Поддержка платформ

Для корректной работы и на Mac (Apple Silicon / linux/arm64) и в CI-окружениях (linux/amd64) используй build-multiplatform при выпуске новой версии.

make build собирает только под текущую платформу — удобно для локальной разработки и проверки.