nextjs-template/ai/nextjs-style-guide/data/rest/clients/auto.md

title, description, keywords

title	description	keywords
Автогенерация из OpenAPI	Генерация REST-клиента из OpenAPI-спецификации через @gromlab/api-codegen.	rest openapi api-codegen автогенерация generated npx

Автогенерация из OpenAPI

Автогенерация используется, когда у API есть актуальная OpenAPI-спецификация. Генератор создаёт TypeScript-клиент, типы и методы API, а разработчик вручную добавляет настройку клиента и GET-хуки.

Пример API

В примерах используется Swagger Petstore:

https://petstore3.swagger.io/api/v3/openapi.json

Имена модуля:

src/infrastructure/pet-store-api/
petStoreApi
pet-store-api.generated.ts

Скрипт генерации

@gromlab/api-codegen не устанавливается в devDependencies. Используем npx @gromlab/api-codegen@latest, чтобы запускать свежую версию.

{
  "scripts": {
    "codegen:pet-store-api": "npx @gromlab/api-codegen@latest -i https://petstore3.swagger.io/api/v3/openapi.json -o src/infrastructure/pet-store-api/generated -n pet-store-api.generated"
  }
}

Параметры:

• -i — путь к OpenAPI-спецификации: URL или локальный файл.
• -o — директория для сгенерированного файла.
• -n — имя сгенерированного файла без .ts.

Ключ --swr не используется. GET-хуки REST-клиента пишутся вручную, чтобы сохранить проектный контракт: один GET-хук = один GET-метод, без бизнес-логики и композиции.

Генерация

npm run codegen:pet-store-api

Ожидаемый результат:

src/infrastructure/pet-store-api/generated/
└── pet-store-api.generated.ts

Сгенерированный файл не правится руками и коммитится в репозиторий.

Проверка методов

После генерации откройте generated/pet-store-api.generated.ts и проверьте фактические имена методов.

Для Petstore нужны GET-операции вида:

petStoreApi.pet.findPetsByStatus(...)
petStoreApi.pet.getPetById(...)

Точные сигнатуры зависят от OpenAPI-схемы и версии генератора. В рабочих задачах всегда сверяйтесь с generated-файлом.

client.ts

Сгенерированный код не должен напрямую использоваться из приложения. Сначала создаётся настроенный инстанс клиента.

// src/infrastructure/pet-store-api/client.ts
import { Api, HttpClient } from './generated/pet-store-api.generated'

const httpClient = new HttpClient({
  baseUrl: 'https://petstore3.swagger.io/api/v3',
  baseApiParams: {
    secure: false,
    headers: {
      'Content-Type': 'application/json',
    },
  },
})

export const petStoreApi = new Api(httpClient)

В реальном проекте вместо строки baseUrl обычно берётся из env-переменной, нормализуется в client.ts и передаётся в HttpClient через конфиг.

client.ts не содержит расширения типов, declare module и Extended-типы. Он только настраивает транспорт и экспортирует инстанс клиента.

Расширение сгенерированных типов

Сгенерированный файл не правится руками. Если OpenAPI-спецификация неполная или генератор дал слишком общий тип (object, unknown, отсутствующее поле), расширения живут в types/.

src/infrastructure/biocad-less-api/
├── generated/
│   └── biocad-less-api.generated.ts
├── types/
│   ├── term.ts
│   └── index.ts
├── client.ts
└── index.ts

Пример расширения generated-типа:

// src/infrastructure/biocad-less-api/types/term.ts
import type { TermRecordItem } from '../generated/biocad-less-api.generated'

declare module '../generated/biocad-less-api.generated' {
  interface TermRecordItem {
    media?: {
      file?: string
      title?: string
      url?: string
    }
  }
}

export type TermRecordItemExtended = Omit<
  TermRecordItem,
  'categories' | 'tags' | 'fields'
> & {
  categories?: Array<{
    _id?: string
    id?: string
    slug?: string
    name?: string
  }>
  tags?: Array<{
    _id?: string
    id?: string
    slug?: string
    name?: string
  }>
  fields?: Record<string, unknown>
}

// src/infrastructure/biocad-less-api/types/index.ts
export type { TermRecordItemExtended } from './term'

declare module используется для добавления отсутствующих полей в generated-интерфейс. Extended-тип используется, когда нужно переопределить неточные поля, не трогая generated-файл.

Публичный API

// src/infrastructure/pet-store-api/index.ts
export { petStoreApi } from './client'
export type { Pet } from './generated/pet-store-api.generated'
export * from './hooks'

Наружу импортируют только из infrastructure/pet-store-api, не из generated/.

Если у модуля есть расширенные типы, они тоже реэкспортируются через index.ts:

// src/infrastructure/biocad-less-api/index.ts
export type { TermRecordItemExtended } from './types'

Регенерация

При изменении OpenAPI-схемы:

npm run codegen:pet-store-api

Что меняется:

• generated/pet-store-api.generated.ts — перезаписывается генератором.
• client.ts, hooks/, types/, index.ts — не трогаются автоматически.

Если после регенерации поменялись сигнатуры методов или типы, это исправляется в ручном коде модуля.

Следующий шаг

После генерации и настройки client.ts проверьте серверный вызов метода клиента или добавьте GET-хук REST-клиента для Client Components.