Тип: справочник · Статус: актуально · Источники истины:
packages/api/openapi/,packages/api/redocly.yaml,packages/api/kubb.config.ts
- Меняйте контракт в
packages/api/openapi/, а не файлы вpackages/api/codegen/. - После изменения запускайте полный
gen, тесты@repo/apiи корневойtsc. - Каноническая версия контракта — OpenAPI 3.2.0. Не понижайте её и не создавайте скрытую 3.1-копию.
- Импортируйте только публичные точки входа пакета;
@repo/api/codegen/*— внутренний код.
Petstore-контракт — пример для проверки генератора, без бэкенда: Next.js не обслуживает /pets.
openapi.yaml подключает остальные части относительными
$ref.
packages/api/openapi/
├── openapi.yaml
├── paths/
│ ├── pets.yaml
│ └── pets-by-id.yaml
└── components/
├── parameters/
├── responses/
└── schemas/
Пример содержит пять операций:
| Метод | Путь | operationId |
Успешный ответ |
|---|---|---|---|
GET |
/pets |
findPetsByStatus |
200 PetPage |
POST |
/pets |
createPet |
201 Pet |
GET |
/pets/{petId} |
getPetById |
200 Pet |
PATCH |
/pets/{petId} |
updatePet |
200 Pet |
DELETE |
/pets/{petId} |
deletePet |
204 |
findPetsByStatus принимает массив status; offset задаёт страницу для Infinite Query.
Из корня репозитория:
npm --workspace @repo/api run lint:openapi
npm --workspace @repo/api run gen
npm --workspace @repo/api run test
npm run tscgen выполняет этапы по порядку:
openapi/openapi.yaml и $ref-файлы
→ Redocly lint → Redocly bundle → bundled.yaml
→ Kubb 5: TypeScript, Zod, plugin-client и Faker → очищенный codegen/
→ проверка AST и project helpers: facets, Query, cache tags, mock routes
→ Oxfmt только для codegen/
→ root TypeScript check, включающий codegen/
Команды bundle, generate:client, generate:helpers и format:generated позволяют
диагностировать отдельные этапы. Изменения контракта проверяйте полным gen.
gen:check сохраняет имена и SHA-256 всех файлов codegen/, запускает полный gen и
сравнивает результат, включая новые, удалённые и скрытые файлы. GitLab CI выполняет эту проверку
перед verify:fast. После изменения контракта сначала выполните gen и включите output в diff.
npm --workspace @repo/api run gen:checkformat:generated выполняет два прохода Oxfmt только по generated output. Постгенератор
проверяет наличие response-фабрик для всех операций с телом; при изменении ожидаемой формы
Kubb output генерация останавливается.
- Node.js 24, npm 11, компилятор приложения TypeScript 7.0.2;
- Kubb 5.5.6 и adapter-oas 5.5.6;
- plugin-ts 5.0.5, plugin-zod 5.4.3, plugin-client 5.5.4, plugin-faker 5.1.0;
- Zod 4.6.5, TanStack Query 5.104.1, Faker 10.6.0.
Версии плагинов Kubb выпускаются независимо. Прямого compiler workspace TypeScript 6 и Node resolution hook больше нет; корневой TypeScript 7 проверяет конфиг и весь generated output.
Канонический контракт остаётся OpenAPI 3.2.0. Встроенный валидатор Kubb пока объявляет
поддержку только 2.0/3.0/3.1, поэтому adapterOas.validate выключен. Обязательная валидация
выполняется Redocly перед генерацией. Дополнительная проверка сравнивает версию, операции,
методы, пути, path-параметры, теги и response statuses адаптера с тем же bundle.
Это подтверждает используемый Petstore-поднабор контракта, а не произвольные возможности 3.2.
При добавлении новых конструкций OpenAPI отдельно проверяйте их AST, generated types и runtime.
Bundle не понижается и скрытая 3.1-копия не создаётся. Для bodyless responses Kubb создаёт
synthetic unknown schema; guarded post-generation заменяет её на undefined в types и Zod.
plugin-client генерирует операции поверх проектного Fetch-клиента client.ts. Он сохраняет
SDK options, native Response, настройки Next.js и runtime mock mode. Официальный Query-плагин
пока ориентирован на plugin-fetch/plugin-axios, поэтому options factories создаёт небольшой
проектный генератор из Kubb operation types. Готовые React hooks не генерируются.
Фабрики Faker адаптируются генератором для передачи options.faker каждому вложенному вызову.
Глобальный экземпляр не перенастраивается. Для mock request фиксируются seed и reference date.
Zod object schemas сохраняют прежнюю политику: дополнительные поля удаляются при parse.
| Путь | Коммитить | Менять вручную | Назначение |
|---|---|---|---|
openapi/ |
Да | Да | Источник истины |
redocly.yaml |
Да | Да | Валидация и bundle |
kubb.config.ts, generators/ |
Да | Да | Generation и post-generation |
Public facets и client-config.ts |
Да | Да | Стабильный API и runtime transport |
bundled.yaml |
Нет | Нет | Временный bundle Redocly |
codegen/ |
Да | Нет | Generated implementation |
Kubb использует output.clean: true: следующий gen удалит ручные и устаревшие файлы из
codegen/. Меняйте источник, конфиг или постгенератор и повторяйте генерацию.
| Путь | Содержимое |
|---|---|
types/ |
OpenAPI types и as const enum objects |
clients/ |
SDK с path/query/body options поверх проектного транспорта |
schemas/, schema-facade.ts |
Zod 4 schemas и публичные z... aliases |
query.ts |
Query/mutation/infinite options и tagged keys |
faker/, mocks.ts |
Faker factories и публичные request/response aliases |
cache-tags/ |
Server-only cache tag namespaces |
mock-client-routes.ts |
Method/path/status → Faker factory |
Числовые алиасы вроде Pet2, порядок файлов и пути плагинов не входят в контракт приложения.
import type { Pet } from '@repo/api'
import { getPetById, PetStatus } from '@repo/api'
import { pets } from '@repo/api/cache-tags' // только server
import { client, createClient } from '@repo/api/client'
import { fakePet } from '@repo/api/mocks'
import { getPetByIdOptions } from '@repo/api/query'
import { zPet } from '@repo/api/schemas'Доступны ровно шесть точек входа: @repo/api, /client, /query, /schemas, /mocks и
/cache-tags. exports направляет их на сгенерированные точки входа и рукописные runtime-адаптеры.
Внутренности codegen/ и числовые алиасы зависят от версии генератора: не импортируйте их.
Параметры пути передаются в path, строки запроса — в query, тело JSON — в body:
const result = await getPetById({
path: { petId: 'pet_123' },
})
if (result.error !== undefined) {
// result.data === undefined; result.error типизирован по documented responses.
return
}
result.data.name
result.responseПри ошибке HTTP SDK по умолчанию возвращает { data: undefined, error, response }.
Для исключений включите throwOnError:
const { data, response } = await getPetById({
path: { petId: 'pet_123' },
throwOnError: true,
})Успешный JSON-ответ проверяется сгенерированной схемой Zod; невалидный возвращает ZodError в error по умолчанию и бросает его при throwOnError: true.
DELETE с описанным статусом 204 возвращает data: undefined и исходный Response.
Нативные опции Fetch/Next.js передаются вместе с опциями SDK:
await getPetById({
cache: 'force-cache',
next: { revalidate: 60, tags: ['pets', 'pets:petId:pet_123'] },
path: { petId: 'pet_123' },
})Генератор создаёт фабрики опций, а не готовые хуки use...:
'use client'
import { createPetMutation, getPetByIdOptions } from '@repo/api/query'
import { useMutation, useQuery } from '@tanstack/react-query'
const pet = useQuery(getPetByIdOptions({ path: { petId } }))
const create = useMutation(createPetMutation())
create.mutate({ body: { name: 'Pixel' } })Ключи запросов и мутаций включают теги OpenAPI. Для пагинации по смещению дополняйте сгенерированные опции Infinite Query правилами экрана:
const pets = useInfiniteQuery({
...findPetsByStatusInfiniteOptions({
query: { limit: 20, status: ['available'] },
}),
initialPageParam: 0,
getNextPageParam: (lastPage) => {
const nextOffset = lastPage.offset + lastPage.limit
return nextOffset < lastPage.total ? nextOffset : undefined
},
})Числовой pageParam заменяет только query.offset, сохраняя фильтры, лимит, заголовки, путь и
остальные опции. В компоненте явно импортируйте useInfiniteQuery и фабрику.
- Добавьте схемы, параметры и ответы в
openapi/components/. - Опишите путь в
openapi/paths/и подключите его вopenapi.yaml. - Укажите уникальный
operationId, обязательныйsummary, корректные теги и ответы. - Запустите
lint:openapiи полныйgen. - Проверьте diff сгенерированного кода и экспортов пакета: имена, обязательность, статусы, ключи запросов, моки и теги кеша.
- Запустите тесты
@repo/apiи корневойtsc. - Повторите
genи убедитесь, что второй запуск ничего не меняет.
Не копируйте сгенерированные Zod-схемы в src/schemas. Для тестов и Storybook берите фабрики
из @repo/api/mocks, если нужная уже есть.