OpenAPI Generator, bir OpenAPI veya Swagger spesifikasyonunu çalışan koda dönüştüren açık kaynaklı bir araçtır: istemci SDK'ları, sunucu taslakları ve yapılandırma dosyaları. CLI'ını kurar, spesifikasyonunuza yönlendirir, `typescript-axios` veya `spring` gibi bir jeneratör seçer ve kodu bir çıktı klasörüne yazar. Bu kılavuz, onu nasıl kuracağınızı, mevcut jeneratörleri nasıl listeleyeceğinizi ve çeşitli diller için istemciler ile sunucular üreteceğinizi gösterir.
OpenAPI Generator Nedir
OpenAPI Generator, makine tarafından okunabilir bir API açıklamasını okur ve ondan kaynak kodu çıkarır. Ona bir `openapi.yaml` (veya JSON) dosyası verdiğinizde, o API'yi çağırmak için bir istemci kütüphanesi, onu uygulayan bir sunucu taslağı, ayrıca belgeler ve yapılandırma üretebilir.
Hem OpenAPI v2 (eski Swagger formatı) hem de OpenAPI v3'ü destekler. Proje, GitHub'daki OpenAPITools organizasyonu tarafından, düzinelerce dil ve framework için şablonlarla sürdürülmektedir.
Temel fark: bu bir kod üreteci, belge üreteci değil. Swagger UI veya Redoc gibi belge araçları spesifikasyonunuzu insan tarafından okunabilir HTML sayfalarına dönüştürür. OpenAPI Generator ise derleyip göndereceğiniz kodu üretir. Markdown belgeleri de üretebilir, ancak asıl işi SDK'lar ve taslaklardır.
Swagger Codegen ile İlişkisi
Swagger Codegen kullandıysanız, OpenAPI Generator size tanıdık gelecektir. Mayıs 2018'de, Swagger Codegen'in 2.3.1 ve 2.4.0 sürümleri arasında, en iyi 40'tan fazla katkıda bulunanı ve şablon yaratıcısı tarafından Swagger Codegen'den çatallandı.
Çatallanma, Swagger Codegen 3.0.0'ın yönü konusundaki anlaşmazlıklar sonucunda gerçekleşti. Topluluk daha hızlı, daha açık bir yayın döngüsü istiyordu. Resmi çatallanma notları projeyi Swagger Codegen 2.4.0-SNAPSHOT'a dayalı olarak tanımlar, bu nedenle ikisi derin köklere sahiptir. İkisini karşılaştırıyorsanız, Swagger Codegen alternatifleri dökümü pratik farklılıkları kapsar.
OpenAPI Generator Kurulumu
Dört yaygın kurulum yolunuz var. Yığınıza uygun olanı seçin.
npm (en yaygın)
npm sarmalayıcısı çoğu ekip için en kolay başlangıç noktasıdır. Temel JAR'ı sizin için indirir ve yönetir.
npm install @openapitools/openapi-generator-cli -g
Global kurulum yapmadan da çalıştırabilirsiniz:
npx @openapitools/openapi-generator-cli version
Homebrew (macOS)
brew install openapi-generator
Bağımsız JAR
OpenAPI Generator bir Java uygulamasıdır, bu nedenle JAR'ı doğrudan Maven Central'dan indirebilir ve Java ile çalıştırabilirsiniz. Bu, npm veya Homebrew katmanını tamamen ortadan kaldırır.
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.23.0/openapi-generator-cli-7.23.0.jar -O openapi-generator-cli.jar
java -jar openapi-generator-cli.jar help
İndirmeden önce en son sürüm numarası için Maven Central'ı kontrol edin.
Docker
Resmi imaj, yerel olarak hiçbir şey kurmanıza gerek kalmadan kod oluşturmanızı sağlar. Çalışma dizininizi kapsayıcıya bağlayın, böylece spesifikasyonunuzu okuyabilir ve çıktıyı geri yazabilir.
docker pull openapitools/openapi-generator-cli
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i /local/openapi.yaml -g go -o /local/out/go
Mevcut Jeneratörleri Listeleme
Herhangi bir şey oluşturmadan önce, hangi jeneratörlerin mevcut olduğunu görün. Her jeneratör, `java`, `python` veya `spring` gibi bir dil ve framework'ü hedefler.
openapi-generator-cli list
Kompakt, satır başına bir görünüm için kısa işareti kullanın ve virgülle ayırın:
openapi-generator-cli list -s | tr ',' '\n'
Liste, istemci jeneratörlerini (bir API'yi çağırmak için) sunucu jeneratörlerinden (birini uygulamak için), ayrıca dokümantasyon ve şema jeneratörlerinden ayırır.
İstemci SDK'sı Oluşturma
Çekirdek komut `generate`'dir. Her seferinde kullanacağınız üç argüman alır:
- `-i, --input-spec` spesifikasyon dosyanızı veya URL'nizi işaret eder.
- `-g, --generator-name` çalıştırılacak jeneratörü seçer.
- `-o, --output` çıktı dizinini ayarlar.
İşte Axios üzerine kurulu bir TypeScript istemcisi:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Bu, `./client` içine tip tanımlı bir istemci yazar. Spesifikasyonunuzdaki her işlem bir metod, her şema ise bir model haline gelir.
Aynı desen diller arasında da çalışır. Jeneratör adını ve çıktı klasörünü değiştirin:
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go
Kod tek bir spesifikasyondan geldiği için, her istemci sözleşmeyle tutarlı kalır. Spesifikasyon değiştiğinde, yeniden oluşturursunuz ve SDK'larınız da buna uyar.
Sunucu Taslakları Oluşturma
Sunucu jeneratörleri yönü tersine çevirir. API'nizi çağıran kod yerine, yönlendirme, istek modelleri ve işleyici arayüzleri bağlı olarak onu uygulayan bir iskelet alırsınız. İş mantığını siz doldurursunuz.
İşte bir Spring Boot sunucu taslağı:
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring
Oluşturulan proje, spesifikasyonunuzla eşleşen denetleyiciler (controller) ve DTO'lar sağlar. Arayüz metotlarını siz uygularsınız ve istek-yanıt yapıları sizin için zaten tanımlanmıştır. Bu, çalışan sunucunun yayınlanmış sözleşmeyle uyumlu kalmasını sağlar.
Çıktıyı Yapılandırma
Varsayılan çıktı nadiren tam olarak istediğiniz gibidir. OpenAPI Generator size çeşitli kontroller sunar.
Ek Özellikler
Çoğu jeneratör, `--additional-properties` (kısa takma ad `-p`) aracılığıyla dil başına seçenekleri sunar. Bunları virgülle ayrılmış `anahtar=değer` çiftleri olarak geçirin:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
--additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Her jeneratör kendi özelliklerini belgeler, bu nedenle kabul ettiği anahtarların tam listesi için jeneratör sayfasını kontrol edin.
Bir Yapılandırma Dosyası
Komut satırı uzadığında, seçenekleri bir yapılandırma dosyasına taşıyın. Hem JSON hem de YAML desteklenir.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -c config.yaml
Bir yapılandırma dosyası, oluşturma ayarlarınızı spesifikasyonun yanında sürüm kontrolünde tutar, bu da derlemeleri tekrarlanabilir hale getirir.
Dosyaları Yoksayma
OpenAPI Generator, çıktı dizinindeki `.openapi-generator-ignore` dosyasını okur. `.gitignore` ile aynı sözdizimini kullanır. Elle düzenlediğiniz dosyaların jeneratör tarafından üzerine yazılmasını durdurmak için kullanın.
# .openapi-generator-ignore
*.md
src/custom/**
Başka bir konumdaki bir yoksayma dosyasına `--ignore-file-override` ile işaret edebilirsiniz.
Özel Şablonlar
Her jeneratör Mustache şablonları tarafından yönlendirilir. Varsayılan çıktı, şirket içi tarzınıza uymuyorsa, şablonları kopyalayın, düzenleyin ve dizininizi `-t` ile geçirin:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
-t ./my-templates
Bu, özel bir başlığa, farklı bir HTTP istemcisine veya her oluşturulan dosyaya dahil edilmiş şirket içi adlandırma kurallarına ihtiyacınız olduğunda doğru araçtır.
CI'da Çalıştırma
Kod üretimi, bir geliştiricinin dizüstü bilgisayarında değil, işlem hattınızda olmalıdır. Her spesifikasyon değişikliğinde istemciyi yeniden oluşturun, böylece commit edilmiş SDK sözleşmeden asla sapmaz. İşte `npx` kullanan bir GitHub Actions adımı:
- name: Generate API client
run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Yeniden oluşturulan çıktı, commit edilmiş olandan farklıysa derlemeyi başarısız edebilirsiniz, bu da senkronizasyon dışına çıkan spesifikasyonları ve SDK'ları yakalar.
Spesifikasyonu Tek Doğruluk Kaynağınız Olarak Tutun
OpenAPI Generator, ona verdiğiniz spesifikasyon kadar iyidir. Çöp girer, çöp çıkar: belirsiz veya geçersiz bir spesifikasyon, belirsiz veya bozuk bir SDK üretir. Bu nedenle en değerli adım, `generate` komutunu çalıştırmadan önce gerçekleşir. Spesifikasyonu doğru, eksiksiz ve kararlı hale getirirsiniz.
İşte Apidog burada devreye girer. Apidog, OpenAPI-native bir hepsi bir arada API platformudur, bu nedenle tasarım çalışmanız ve spesifikasyonunuz aynı yapıdır. API'yi tasarlar veya içe aktarırsınız ve Apidog, OpenAPI belgesini her şeyin akıp gittiği doğruluk kaynağı olarak tutar.
Temiz bir iş akışı şöyle görünür:
- Apidog'da OpenAPI spesifikasyonunu tasarlayın veya içe aktarın. Dal desteği, değişiklikler üzerinde izole bir şekilde çalışmanıza olanak tanır, bu Git ile OpenAPI'yi sürüm kontrolü altında tutmaya benzer.
- Oluşturmadan önce spesifikasyonu doğrulayın ve lint edin. Bir OpenAPI linter ve bir Swagger doğrulayıcıdan geçen bir spesifikasyon, daha az sürprizle daha temiz kod üretir.
- Doğrulanmış spesifikasyonu dışa aktarın, ardından SDK'larınız ve taslaklarınız için OpenAPI Generator'a besleyin.
Spesifikasyonu deponuzla senkronize tutabilirsiniz, örneğin OpenAPI spesifikasyonunu GitHub ile senkronize ederek ve değişiklikleri yayınlamadan önce bir OpenAPI farkı ile gözden geçirebilirsiniz. Eski araçlardan geçiş yapıyorsanız, API tasarımı ve testi için Swagger alternatifleri karşılaştırması iyi bir başlangıç noktasıdır.
Apidog'un Durduğu ve OpenAPI Generator'ın Başladığı Yer
Burada hassas olmakta fayda var. Apidog tam istemci SDK'ları veya sunucu taslakları oluşturmaz. Bu, OpenAPI Generator'ın işidir ve ikisi rekabet etmekten ziyade birbirini tamamlar.
Apidog, her uç nokta için birçok dilde ve HTTP istemcisinde kopyalamaya hazır istemci istek kod parçacıkları sunar. Bunlar, bir pakete dahil SDK değil, bir betiğe yapıştırabileceğiniz istek başına örneklerdir. Oluşturulmuş, sürümlendirilmiş bir kütüphane veya bir sunucu iskeleti için, Apidog'un ürettiği spesifikasyon üzerinde OpenAPI Generator'ı çalıştırırsınız.
Apidog ayrıca, kod üretiminden ayrı olan kendi komut satırı test çalıştırıcısı olan Apidog CLI'yı da sunar. API testlerinizi CI'da çalıştırır; SDK'lar oluşturmaz. Şöyle kurun ve kullanın:
npm install -g apidog-cli@latest
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <testScenarioId> \
-e <envId> \
-r cli,html \
-n 1
Yetkilendirmeyi `--access-token` ile geçirirsiniz, `-t` test senaryosunu seçer, `-e` karşı çalıştırılacak ortamı seçer ve `-r` raporlayıcıları seçer. Güncel bir Node.js LTS sürümünde çalıştırın. Kurulum ayrıntıları için Apidog CLI kurulum kılavuzuna ve komut satırından bir REST API'yi test etme konulu kılavuza bakın.
Yani tam döngü şudur: Apidog'da spesifikasyonu tasarlayın ve doğrulayın, OpenAPI Generator ile SDK'lar ve taslaklar oluşturun, ardından çalışan API'yi Apidog CLI ile doğrulayın.
Apidog'u ücretsiz deneyin, kredi kartı gerekmez.
Sıkça Sorulan Sorular
OpenAPI Generator Nedir?
OpenAPI Generator, OpenAPITools organizasyonundan açık kaynaklı bir araçtır ve bir OpenAPI veya Swagger spesifikasyonundan kod üretir. İstemci SDK'ları, sunucu taslakları, belgeler ve yapılandırma dosyaları üretir ve hem OpenAPI v2'yi hem de v3'ü destekler.
OpenAPI Generator Nasıl Kullanılır?
CLI'yı kurun (örneğin `npm install @openapitools/openapi-generator-cli -g`), ardından üç işaretle `generate` komutunu çalıştırın: spesifikasyonunuz için `-i`, jeneratör için `-g` ve çıktı klasörü için `-o`. Mevcut tüm jeneratörleri görmek için önce `openapi-generator-cli list` komutunu çalıştırın.
OpenAPI Generator Nasıl Çalışır?
Spesifikasyonunuzu dahili bir modele ayrıştırır, ardından bu modeli seçtiğiniz hedef için Mustache şablonları aracılığıyla işler. Her işlem bir metot veya işleyici, her şema ise tip tanımlı bir model haline gelir. Çıktıyı değiştirmek için şablonları `-t` ile geçersiz kılabilirsiniz.
Bir OpenAPI Spesifikasyonundan İstemci SDK'sı Nasıl Oluşturulur?
Bir istemci jeneratörü seçin ve `generate` komutunu çalıştırın. Örneğin, `openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client` tip tanımlı bir TypeScript istemcisi oluşturur. Diğer dilleri hedeflemek için `typescript-axios` yerine `java`, `python` veya `go` kullanın.
Sunucu Taslakları Nasıl Oluşturulur?
Bir sunucu jeneratörü seçin. Bir Spring Boot iskeleti için `openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring` komutunu çalıştırın. Çıktı, spesifikasyonunuzdan denetleyiciler (controller) ve istek modelleri içerir ve işleyici mantığını siz uygularsınız.
OpenAPI Generator ve Swagger Codegen Arasındaki Fark Nedir?
OpenAPI Generator, Mayıs 2018'de, daha hızlı, topluluk odaklı bir yayın döngüsü isteyen 40'tan fazla katkıda bulunanı tarafından Swagger Codegen'den çatallandı. İkisi ortak bir tabanı paylaşır, ancak OpenAPI Generator'ın artık kendi yol haritası, jeneratör seti ve yayın takvimi var.
Bir OpenAPI Spesifikasyonundan PHP SDK'sı Nasıl Oluşturulur?
`php` jeneratörünü kullanın: `openapi-generator-cli generate -i openapi.yaml -g php -o ./client-php`. Oluşturmadan önce tam jeneratör adını onaylamak ve diğer PHP framework seçeneklerini görmek için `openapi-generator-cli list` komutunu çalıştırın.