@gromlab/api-codegen

CLI утилита для генерации TypeScript REST-клиента из OpenAPI спецификации.

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

npx @gromlab/api-codegen -i <INPUT> -o <OUTPUT> [-n <NAME>] [--mode single|split|both]

Аргументы:

• -i, --input <path> - путь к OpenAPI файлу или URL
• -o, --output <path> - директория для сохранения файлов
• -n, --name <name> - имя монолитного файла без .ts
• --mode <mode> - режим генерации: single, split, both (по умолчанию single)
• --single-file - устаревший алиас для --mode single

Примеры

# Локальный файл
npx @gromlab/api-codegen -i ./openapi.json -o ./src/api

# URL на спецификацию
npx @gromlab/api-codegen -i https://httpbin.org/spec.json -o ./src/api

# Монолитный файл с кастомным именем
npx @gromlab/api-codegen -i ./openapi.json -o ./src/api -n MyApi

# Разложенный tree-shaking friendly клиент
npx @gromlab/api-codegen -i ./openapi.json -o ./src/api --mode split

# Монолит и разложенный клиент одновременно
npx @gromlab/api-codegen -i ./openapi.json -o ./src/api -n MyApi --mode both

Структура вывода

По умолчанию генерируется legacy монолитный клиент для обратной совместимости:

generated/
└── MyApi.ts

В режиме split генерируется tree-shaking friendly структура:

generated/
├── create-api-client.ts
├── data-contracts.ts
├── http-client.ts
├── index.ts
└── operations/
    ├── index.ts
    ├── get-users.ts
    └── create-user.ts

Каждый endpoint лежит в отдельном файле внутри operations/.

В режиме both генерируются оба варианта рядом.

Пример Использования

Для single режима:

import { Api, HttpClient } from './generated/MyApi';

const http = new HttpClient({ baseUrl: 'https://api.example.com' });
const api = new Api(http);

const users = await api.users.getAll({});

Для split режима:

import { createApiClient, HttpClient } from './generated';
import { getAll } from './generated/operations/get-all';
import { create } from './generated/operations/create';

const http = new HttpClient({
  baseUrl: 'https://api.example.com',
  securityWorker: (securityData: { token: string } | null) => {
    if (!securityData?.token) {
      return undefined;
    }

    return {
      headers: {
        Authorization: `Bearer ${securityData.token}`,
      },
    };
  },
});

const api = createApiClient(http, {
  users: {
    getAll,
    create,
  },
});

const users = await api.users.getAll({});
const createdUser = await api.users.create({ email, password });

Если нужен максимально точечный импорт, operation можно вызвать напрямую:

import { HttpClient } from './generated/http-client';
import { getAll } from './generated/operations/get-all';

const http = new HttpClient();
const users = await getAll(http, {});

Разработка

Сборка

bun run build

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

bun test
bun run test:unit
bun run test:integration

Подробная документация по тестированию в tests/README.md.

Лицензия

MIT