Импорт OpenAPI

Если у сервиса, который вы мокаете, есть спецификация OpenAPI 3.x, моки заводятся из неё пачкой — кнопкой «Импортировать JSON» в подвале списка моков или запросом POST /api/mocks/import. Разбор берётся из того же пакета, которым собран каталог методов Ozon и Wildberries.

Как запустить

Формат определяется по первому символу: текст, начинающийся с {, разбирается как JSON, всё остальное — как YAML. Диалог кабинета передаёт только document и pathPrefix, поэтому из кабинета моки всегда создаются черновиками и не более ста за раз.

curl -X POST localhost:8080/api/mocks/import \
  -H 'content-type: application/json' \
  -d '{"document": "<текст спецификации>", "pathPrefix": "/custom/erp2"}'

{"created":2,"skipped":0,"examples":["GET /custom/erp2/orders","PUT /custom/erp2/orders/{id}"],"leftOver":0,"limit":100}

Что импорт понимает

• Операции из paths. Берутся методы GET, POST, PUT, PATCH, DELETE; HEAD и OPTIONS пропускаются — движку своих моков нечего на них отдавать.
• Код ответа: первый из описанных, попадающий в диапазон 2xx. Если такого нет — 200.
• Тело ответа: пример из content.application/json. Сначала example, затем первый из examples (у него разворачивается обёртка value).
• Название мока: первое предложение из summary, иначе из description, обрезанное до 110 символов; если ни того ни другого нет — сам путь.
• Локальные ссылки $ref вида #/components/... — разыменовываются, в том числе вложенные.

Адрес мока склеивается как «префикс + путь из спецификации». Фигурные скобки в пути сохраняются и работают как параметры: /custom/erp2/orders/{id} совпадёт с /custom/erp2/orders/A-42, а {{params.id}} в теле вернёт A-42.

Что игнорируется

Кроме схемы ответа, импорт не переносит:

• servers и базовые адреса — путь всегда живёт под вашим префиксом внутри /custom;
• parameters, requestBody и security — валидации запроса у своих моков нет, мок отвечает одинаково на любой запрос по своему адресу;
• ответы с кодами 4xx: сценариев ошибок у своих моков нет, код ответа один;
• внешние $ref на другие файлы и адреса — такая ссылка остаётся неразвёрнутой;
• tags, deprecated, описания параметров и всё остальное, что не влияет на ответ.

Каждый созданный мок получает contentType: application/json, задержку 250 мс и включённую шаблонизацию — то же, что у мока, созданного руками.

Конфликты путей

Три ситуации, в которых операция не станет моком, и все три видны в ответе.

Повторный импорт того же файла безопасен и осмыслен: уже созданные моки уйдут в skipped, а очередь за потолком продвинется дальше. Живой ответ на второй импорт того же файла и на импорт с limit: 1:

{"created":0,"skipped":2,"examples":[],"leftOver":0,"limit":100}
{"created":1,"skipped":0,"examples":["GET /custom/erp3/orders"],"leftOver":1,"limit":1}

Обрезка длинного пути не делается специально: две разные операции, укороченные до 300 символов, склеились бы в один адрес, и вторая молча ушла бы в дубли.

Ошибки разбора