Мок-сервер

Обзор

Мок-сервер генерирует фиктивные ответы API на основе ваших OpenAPI-схем. Он позволяет тестировать интеграцию API без выполнения реальных HTTP-вызовов. Это полезно для разработки, тестирования LLM-агентов и демонстраций.

Мок-сервер — это отдельный бинарник — swag2mcp-mock. Он не входит в основной бинарник swag2mcp и должен быть установлен отдельно.

Установка

# Вариант 1: Скачать из GitHub Releases
# Ищите swag2mcp-mock_<version>_<os>_<arch>.tar.gz

# Вариант 2: Установить через Go
go install github.com/mmadfox/swag2mcp/cmd/swag2mcp-mock@latest

Конфигурация

Включите мок-сервер в вашем конфиге:

mock_enabled: true
mock_auth:
  oauth2_port: 9090
  digest_port: 9091
  hmac_port: 9092

specs:
  - domain: jokes
    llm_title: Dad Joke API
    base_url: https://icanhazdadjoke.com
    collections:
      - llm_title: Jokes
        location: https://raw.githubusercontent.com/mmadfox/swag2mcp/main/specs/dadjoke.yaml
        base_mock_url: "127.0.0.1:9090"

Параметры

mock_enabled

• Тип: bool
• По умолчанию: false
• Эффект: При true каждая активная коллекция должна иметь установленный base_mock_url. Мок-сервер запускает HTTP-серверы для каждой коллекции.

mock_auth

Порты для мок-серверов аутентификации. Они симулируют конечные точки OAuth2, Digest и HMAC, чтобы вы могли тестировать API с аутентификацией без реальных учётных данных.

Поле	По умолчанию	Описание
oauth2_port	9090	Порт для мок-сервера OAuth2-токенов
digest_port	9091	Порт для мок-сервера Digest-аутентификации
hmac_port	9092	Порт для мок-сервера HMAC-аутентификации

base_mock_url (на коллекцию)

• Тип: string
• Обязательный: Да (когда mock_enabled: true)
• Формат: host:port (например, localhost:8080, 127.0.0.1:9000)
• Эффект: Каждая коллекция получает свой собственный HTTP-сервер на этом адресе. Сервер отвечает на все эндпоинты, определённые в спецификации, случайно сгенерированными данными.

Запуск мок-сервера

# Запуск с конфигом по умолчанию
swag2mcp-mock

# Запуск с TLS
swag2mcp-mock --tls

# Запуск с пользовательским TLS-сертификатом
swag2mcp-mock --tls --tls-cert cert.pem --tls-key key.pem

TLS-флаги

Флаг	Описание
--tls	Включить TLS с самоподписанным сертификатом
--tls-cert	Путь к файлу TLS-сертификата
--tls-key	Путь к файлу TLS-ключа

Если --tls установлен без --tls-cert и --tls-key, самоподписанный сертификат генерируется автоматически для localhost.

Что делает мок-сервер

При запуске мок-сервер:

1. Парсит все файлы спецификаций — читает OpenAPI/Swagger-спецификацию каждой коллекции
2. Регистрирует обработчики — создаёт HTTP-обработчик для каждого пути и метода, определённых в спецификации
3. Генерирует фиктивные данные — отвечает случайно сгенерированными данными, соответствующими схеме ответа (правильные типы, форматы и структура)
4. Запускает серверы аутентификации — симулирует конечные точки OAuth2, Digest и HMAC для тестирования

Тестирование мока

# В одном терминале:
swag2mcp-mock

# В другом терминале:
curl http://localhost:8080/pets
# → [{"id":1,"name":"Pet_name","status":"available"}]

Как генерируются фиктивные данные

Мок-сервер генерирует реалистичные фиктивные данные на основе OpenAPI-схемы:

• Строки — случайные слова, предложения или значения, специфичные для формата (email, URL, UUID, дата, телефон и т.д.)
• Числа — случайные целые числа и числа с плавающей точкой в указанном диапазоне
• Булевы — случайные true/false
• Массивы — от 1 до 3 случайных элементов
• Объекты — все свойства заполнены случайными значениями
• Перечисления — случайное значение из списка перечисления
• Nullable-поля — иногда возвращает null (~10% вероятность)

Варианты использования

• Разработка — тестируйте интеграцию без доступа к реальному API
• Тестирование LLM-агентов — проверьте, что LLM может обнаруживать, проверять и вызывать эндпоинты
• Демонстрации — покажите swag2mcp в работе без настройки реальных API
• Нагрузочное тестирование — тестируйте MCP-сервер под нагрузкой без обращения к реальным API

Важные замечания

• Отдельный бинарник — swag2mcp-mock не входит в основной бинарник swag2mcp. Устанавливайте его отдельно.
• Каждая коллекция получает свой порт — настраивайте base_mock_url для каждой коллекции
• Мок-серверы аутентификации глобальны — серверы OAuth2, Digest и HMAC работают на настроенных портах независимо от количества коллекций
• Ошибки парсинга спецификаций не фатальны — если спецификацию коллекции не удалось распарсить, она пропускается с предупреждением
• Самоподписанный TLS — при использовании --tls без сертификатов генерируется самоподписанный сертификат только для localhost