🧘 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