import

Назначение

Импортировать файлы спецификаций в директорию specs/ рабочей области для локального использования, или восстановить полную рабочую область из ZIP-архива. Три режима покрывают различные сценарии: добавление одной спецификации, массовый импорт из существующего конфига, или восстановление полной рабочей области.

Когда использовать

• У вас есть URL или файл спецификации, и вы хотите сохранить его локально в рабочей области
• Вы хотите загрузить все файлы спецификаций коллекций из конфига и сделать рабочую область самодостаточной
• Вам нужно восстановить рабочую область из ZIP-архива, созданного командой export
• Вы переносите swag2mcp на другую машину

Синтаксис

swag2mcp import [path] [source] [name] [flags]

Аргументы

Аргумент	Позиция	Обязательно	Описание
path	1	Нет	Директория рабочей области. Если не указан, разрешается по правилам разрешения пути.
source	2	По ситуации	URL или локальный путь к файлу спецификации, или путь к ZIP-архиву
name	3	По ситуации	Имя файла для сохранения (например, example-api.yaml). Если не указан, определяется из URL.

Флаги

Флаг	Сокращение	Тип	По умолчанию	Описание
--spec	-s	string	""	Загрузить файлы спецификаций коллекций из конфига. Без значения — все specs, или указать домены через запятую, например --spec meteo,github
--force	-f	bool	false	Перезаписывать существующие файлы спецификаций без ошибки
--from-zip		string	""	Восстановить рабочую область из ZIP-архива swag2mcp

Как это работает

Режим 1 — Одиночный импорт из URL или файла

Загрузить файл спецификации и сохранить его в specs/:

swag2mcp import https://example.com/spec.yaml example-api.yaml
swag2mcp import /path/to/workspace https://example.com/spec.yaml example-api.yaml
swag2mcp import ./local-spec.yaml example-api.yaml

Если name не указан, он определяется из имени файла в URL:

swag2mcp import https://example.com/specs/petstore.yaml
# → сохранён как petstore.yaml

Перезаписать существующий файл с помощью --force:

swag2mcp import --force https://example.com/spec.yaml example-api.yaml

После импорта вывод показывает путь к рабочей области, сохранённый файл и YAML-шаблон для добавления в swag2mcp.yaml:

✅ Imported to /path/to/workspace
   specs/example-api.yaml

   Add to swag2mcp.yaml:
     specs:
       - domain: <your-domain>
         collections:
           - location: specs/example-api.yaml

Режим 2 — Массовый импорт из существующего конфига (--spec)

Загрузить все файлы спецификаций коллекций для указанных доменов из их настроенных URL location, сохранить в specs/ и обновить конфиг, чтобы он указывал на локальные копии:

swag2mcp import --spec                # все specs
swag2mcp import --spec meteo           # конкретный spec
swag2mcp import --spec meteo,github    # несколько specs
swag2mcp import /path/to/workspace --spec meteo

Если указанный домен не существует в конфиге, команда возвращает ошибку:

Error: import_no_match
  Spec "nonexistent" not found in config.

После этого рабочая область становится самодостаточной — удалённые URL спецификаций больше не нужны.

Режим 3 — Восстановление из ZIP-архива

Восстановить полную рабочую область из ZIP-архива, созданного командой swag2mcp export:

swag2mcp import --from-zip /path/to/backup.zip
swag2mcp import /path/to/workspace /path/to/backup.zip

ZIP должен быть создан командой swag2mcp export. Произвольные ZIP-файлы не подойдут — архив имеет определённую внутреннюю структуру (swag2mcp.yaml, specs/, auth_scripts/).

Проверка после команды

# Одиночный или массовый импорт
swag2mcp ls [path]
# Новая спецификация должна появиться в списке

# Восстановление из ZIP
swag2mcp ls [path]
# Все спецификации из резервной копии должны появиться

Нюансы

• Массовый режим требует конфиг: При использовании --spec файл конфигурации должен существовать. При необходимости сначала выполните init.
• Одиночный импорт создаёт рабочую область: Если рабочая область не существует, она создаётся автоматически.
• Определение ZIP: Позиционный аргумент, заканчивающийся на .zip, обрабатывается как ZIP-источник. Флаг --from-zip имеет приоритет над позиционным определением.
• HTTP-клиент: Глобальные настройки HTTP-клиента из конфига применяются во время импорта (таймаут, прокси, заголовки и т.д.).