swagger-zen

🧘 Swagger-Zen

Swagger-Zen, OpenAPI/Swagger şemalarından tam bir API ekosistemi oluşturmak için tasarlanmış kapsamlı ve otomatik bir araçtır.

🚀 Özellikler

• ✅ OpenAPI/Swagger şemalarından Zodios API istemcileri oluşturur
• ✅ Zod doğrulama şemaları üretir
• ✅ TypeScript türlerini otomatik olarak oluşturur
• ✅ MSW (Mock Service Worker) mock handler'larını üretir
• ✅ Vitest uyumlu otomatik test dosyaları oluşturur
• ✅ API Kullanım Dokümantasyonu (USAGE.md) oluşturur
• ✅ Şema değişikliklerini takip eder, diff raporu üretir

⚙️ Kurulum

# Global kurulum
npm install -g swagger-zen

# veya proje bazlı (devDependency olarak) kurulum
npm install --save-dev swagger-zen

⚡ Hızlı Başlangıç

En basit kullanım:

npx swagger-zen

Bu komut, varsayılan ayarlarla çalışır.

Özel Konfigürasyon Kullanımı

npx swagger-zen --config swagger-zen.config.js

📁 Konfigürasyon Dosyası

Proje root dizininde swagger-zen.config.js adında bir dosya oluşturun:

module.exports = {
  url: 'https://api.example.com/openapi.json',
  baseApiDir: 'src/api',
  outputDir: 'src/api/__generated__',
  typesFile: 'src/api/types.ts',
  mockIndex: 'src/api/msw.ts',
  testFile: 'src/api/__generated__/api/tests/auto.spec.ts',
  docsFile: 'src/api/USAGE.md',
  snapshotDir: 'swagger/snapshots',
  noDiff: false,
  dryRun: false
};

🔧 Konfigürasyon Seçenekleri

Seçenek	Açıklama	Varsayılan Değer
url	OpenAPI/Swagger şema URL'i	https://api.example.com/openapi.json
baseApiDir	API dosyaları için temel dizin	src/api
outputDir	Oluşturulan dosyalar için dizin	src/api/__generated__
typesFile	TypeScript türleri için dosya yolu	src/api/types.ts
mockIndex	MSW mock'ları için indeks dosyası	src/api/msw.ts
testFile	Otomatik oluşturulan testler için dosya yolu	src/api/__generated__/api/tests/auto.spec.ts
docsFile	API dokümantasyonu için dosya yolu	src/api/USAGE.md
snapshotDir	Şema anlık görüntüleri için dizin	swagger/snapshots
noDiff	Diff oluşturmayı atla	false
dryRun	Dosya yazmadan çalıştır	false

🧪 Komut Satırı Seçenekleri

swagger-zen [seçenekler]

Seçenekler:

  -v, --version            Sürüm numarasını gösterir
  -c, --config <dosya>     Konfigürasyon dosyası yolu
  -u, --url <url>          OpenAPI/Swagger URL
  --dry-run                Dosya yazmadan çalıştır
  --no-diff                Diff oluşturmayı atla
  --verbose                Detaylı günlük kayıtları
  -h, --help               Bu yardım metnini gösterir

🧾 Örnek Kullanım

package.json Entegrasyonu

"scripts": {
  "api:update": "swagger-zen"
}

CI/CD Entegrasyonu

API şema değişikliklerini CI ortamında kontrol etmek için:

npx swagger-zen --no-diff