OpenAPI TypeScript Type Generation

Proje: OkulUp · Hub: OkulUp — Decisions

Karar: OpenAPI’dan Otomatik Tip Üretimi

Karar

Backend API’nin OpenAPI spec’inden (kampusapi/kampus/storage/api-docs/api-docs.json) TypeScript tipleri otomatik üretiliyor.

npm run api:generate
# openapi-typescript ../kampusapi/kampus/storage/api-docs/api-docs.json -o src/generated/api.ts

src/generated/api.ts → components['schemas']['UserResource'] gibi referanslar

Üst seviye tipler (e.g., User, Announcement) bu generated type’ları extend ederek kullanıyor:

type UserResource = RequireKeys<
  Omit<components['schemas']['UserResource'], ...>,
  'id' | 'name' | ...
>;
export interface User extends UserResource { ... }

Why: API ve frontend’in tip uyumunu garantilemek için. Backend model değiştiğinde api:generate çalıştırınca frontend tipleri güncellenebilir. Manuel tip yazmak yerine backend contract source of truth.

How to apply: Backend’de model veya API response değişince npm run api:generate çalıştır, ardından etkilenen yerler TypeScript hataları verecek.

npm run api:check → CI’da kullanılabilir, üretilen tipler değiştiyse fail eder.

Related

• service-layer-pattern — generated type kullanımı