S.Gromov
bf340b3dbe
- добавлен режим генерации single, split и both - добавлены отдельные operation-файлы и createApiClient - удалена генерация SWR-хуков и зависимости React/SWR - обновлены CLI, шаблоны, примеры, документация и тесты - версия пакета повышена до 3.0.0
141 lines
3.6 KiB
Markdown
141 lines
3.6 KiB
Markdown
# @gromlab/api-codegen
|
||
|
||
CLI утилита для генерации TypeScript REST-клиента из OpenAPI спецификации.
|
||
|
||
## Использование
|
||
|
||
```bash
|
||
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`
|
||
|
||
## Примеры
|
||
|
||
```bash
|
||
# Локальный файл
|
||
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 монолитный клиент для обратной совместимости:
|
||
|
||
```text
|
||
generated/
|
||
└── MyApi.ts
|
||
```
|
||
|
||
В режиме `split` генерируется tree-shaking friendly структура:
|
||
|
||
```text
|
||
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` режима:
|
||
|
||
```typescript
|
||
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` режима:
|
||
|
||
```typescript
|
||
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 можно вызвать напрямую:
|
||
|
||
```typescript
|
||
import { HttpClient } from './generated/http-client';
|
||
import { getAll } from './generated/operations/get-all';
|
||
|
||
const http = new HttpClient();
|
||
const users = await getAll(http, {});
|
||
```
|
||
|
||
## Разработка
|
||
|
||
### Сборка
|
||
|
||
```bash
|
||
bun run build
|
||
```
|
||
|
||
### Тестирование
|
||
|
||
```bash
|
||
bun test
|
||
bun run test:unit
|
||
bun run test:integration
|
||
```
|
||
|
||
Подробная документация по тестированию в [`tests/README.md`](tests/README.md).
|
||
|
||
## Лицензия
|
||
|
||
MIT
|