typescript-openapi-generator

typescript-openapi-generator — обёртка над orval.

Для кого пакет

Для фронтенд-разработчиков, работающих с ENSI.

Зачем он нужен

• Меньше ручной работы: не нужно вручную писать хуки и обновлять типы под каждый endpoint из OpenAPI — код генерируется автоматически.
• Проще встраивать API: интеграция с react-query — запросы, мутации и кэш без лишней сложности.

Зачем обёртка над Orval

У Orval есть ограничения на сложные схемы. Пакет сначала разрешает общую схему, затем передаёт результат в Orval для сериализации.

Как пользоваться

Установка

Пакет ставьте в devDependencies — он нужен для генерации кода, а не в рантайме приложения.

npm i -D @ensi-platform/typescript-openapi-generator

или

yarn add -D @ensi-platform/typescript-openapi-generator

или

pnpm add -D @ensi-platform/typescript-openapi-generator

Инициализация конфигурации

Выполните:

typescript-openapi-generator-init

Будет создан файл typescript-openapi-generator.ts.

Параметры, которые правят в typescript-openapi-generator.ts:

| Поле | Назначение | Пример | |------|------------|--------| | cache > input | Точка входа OpenAPI: URL http/https, URL file:// или путь в ФС (относительные пути считаются от каталога, из которого запускают typescript-openapi-generator-generate) | См. источники входа | | cache > output | Каталог, куда сохранять сгенерированные файлы | ./output/src/api | | loaderOptions | Дополнительные настройки загрузчика | — | | loaderOptions > parseItem | Обход схем при загрузке; можно обработать особые случаи или подставить значения по умолчанию | — | | orval | Настройки Orval (документация) | — |

Источники входа (cache[].input)

• Удалённый URL — как раньше; указывайте корневой файл спеки (например index.yaml).

• Путь в файловой системе — относительно текущего каталога запуска или абсолютный; внутри инструмент приводит его к file: URL.

  // Относительно cwd (удобно в репозитории)
  input: './specs/openapi/index.yaml',
  
  // Абсолютный путь (macOS / Linux)
  input: '/Users/you/project/specs/openapi/index.yaml',

• URL file:// — если уже есть file URL или нужен путь в виде URL. Строка должна начинаться с file://; нормализация как в Node.js для file: URL.

  macOS / Linux — после file: три слэша для абсолютного пути (file:// + / + путь):

  input: 'file:///Users/you/project/specs/openapi/index.yaml',

  Windows — в URL без обратных слэшей; прямые слэши и форма без хоста file:///C:/...:

  input: 'file:///C:/Users/you/project/specs/openapi/index.yaml',

  Если в пути есть пробелы или другие зарезервированные символы — закодируйте их в строке file:// (например пробел → %20) либо укажите обычный путь в input без префикса file://.

Генерация

Сохраните конфиг и выполните:

typescript-openapi-generator-generate

Команда обходит все $ref в схемах OpenAPI, подтягивает файлы, собирает одну согласованную спецификацию и передаёт её в Orval.