sgcOpenAPI ve Swagger Codegen Karşılaştırması — Delphi İstemcilerini Daha Hızlı Üretin

Sorun: çoğu modern API, Delphi SDK'sı değil bir OpenAPI spec'i sunar

Delphi'de bir modern REST API'sini hiç entegre ettiyseniz, iş akışı muhtemelen şöyle görünüyordu: belgeleri okuyun, TIdHTTP veya TNetHTTPClient etrafına elle bir sarmalayıcı yazın, istek gövdelerini dize sabitlerine yapıştırın, yanıtları TJSONObject ile ayrıştırın, TDateTime serileştirmesiyle uğraşın ve her uç nokta için tekrarlayın. İşe yarar ama ölçeklenmez. API'nin 80 uç noktası vardır, siz bunların 8'ini sararsınız, satıcı gelecek ay 10 tane daha ekler ve sarmalayıcınız çürür.

OpenAPI'nin (eski adıyla Swagger) vaadi şudur: satıcı, makine tarafından okunabilen bir açıklama (tek bir YAML veya JSON dosyası) yayınlar ve bir üreteç bunu seçtiğiniz dilde türlenmiş bir istemciye dönüştürür. Çoğu dil için bu son derece iyi çalışır: openapi-generator ve swagger-codegen, Python, TypeScript, Go, Java, C#, Rust ve diğer birçok dil için deyimsel istemciler üretir.

Delphi için bu hikaye tarihsel olarak daha az sorunsuz olmuştur. Bu yazı, 2026 itibarıyla iki ana seçeneği (uzun süredir var olan açık kaynaklı swagger-codegen Delphi üretecini ve eSeGeCe'nin yerel ticari sgcOpenAPI ürününü) karşılaştırır ve her birinin aynı girdi spec'inden ne ürettiğini gösterir.

swagger-codegen ve openapi-generator hakkında

Artık SmartBear çatısı altında olan Swagger projesi, swagger-codegen ürününü sunar. 2018'deki bir topluluk çatallamasının ardından paralel bir proje olan openapi-generator, birçok dil için fiilî standart haline geldi. Her iki araç da Mustache şablonları aracılığıyla uzun bir hedef dil listesini destekler. Bir Delphi üreteci (swagger-codegen içindeki delphi ve ayrıca topluluk şablonları) vardır, ancak bu her zaman ara sıra gönüllüler tarafından bakımı yapılan ikinci sınıf bir hedef olmuştur.

Bu yazının yazıldığı sırada, openapi-generator içindeki Delphi şablonu, eski Delphi sürümlerinde derlenen ancak modern Delphi'de (D11/D12/D13) bilinen sorunları olan kod üretir: null yapılabilir alanların yanlış işlenmesi, daha yeni RTL için eksik {$IFDEF} koruyucuları, OpenAPI 3.1 desteğinin olmaması, akış yanıtı desteğinin olmaması ve belirli bir HTTP istemci kütüphanesi sürümüne bağlı bir çalışma zamanı. Delphi üretecine karşı açılan uzun süredir devam eden GitHub sorunlarının birçoğu yıllardır açık. Sonuçlar spec'e göre değişir.

sgcOpenAPI hakkında

sgcOpenAPI, eSeGeCe'nin yerel bir Delphi aracıdır. OpenAPI 3.0 (ve artık 3.1) spesifikasyonlarını ayrıştırır ve sgc adlandırma kurallarını izleyen Delphi birimleri üretir: istemci için Tsgc[Api]Client, her şema nesnesi için Tsgc[Api]_[Model] ve işlem başına bir metot. Üretilen kod, taşıma olarak sgcWebSockets'ten TsgcHTTPComponentClient kullanır; böylece kimlik doğrulama, yeniden deneme, TLS ve HTTP/2 ücretsiz olarak devralınır.

Üreteç kendisi Delphi'de yazıldığından, bir Delphi aracına gömülebilir, komut satırından çalıştırılabilir veya bir derleme betiğinden çağrılabilir. Çıktı, sgcWebSockets dışında çalışma zamanı bağımlılığı olmayan düz .pas dosyalarıdır; JVM yok, Node yok, Python yok, şablon motoru yok.

Özellik karşılaştırması

Özellik	swagger-codegen / openapi-generator (Delphi hedefi)	sgcOpenAPI
OpenAPI 2.0 (Swagger)	Evet	Evet
OpenAPI 3.0	Evet (openapi-generator)	Evet
OpenAPI 3.1	Bu yazı yazıldığında sınırlı	Evet
Çalışma zamanı gereksinimi	Üreteci çalıştırmak için Java 11+	Yok (yerel Delphi exe)
Hedef Delphi sürümleri	D10.x'te en iyi çaba, bu yazı yazıldığında D11+ üzerinde sıklıkla bozuk	D7'den D13'e kadar
HTTP arka ucu	Mevcut Delphi şablonlarında varsayılan olarak Indy	sgcHTTPComponentClient (Indy / ICS / SChannel, ayrıca HTTP/2)
Eşzamansız / akış yanıtları	Sınırlı	Evet
OAuth2 / API anahtarı / bearer kimlik doğrulama	Kısmi	Evet, yerel bileşenler
Çok biçimlilik (oneOf, allOf, discriminator)	Sınırlı	Evet
Null yapılabilir alanlar	Tutarsız	Evet (TsgcNullable<T>)
Dosya yükleme / multipart	Kısmi	Evet
Sunucu saplaması üretimi	Evet (çoğunlukla diğer diller)	Evet (sgcWebSocketHTTPServer ile Delphi sunucu saplamaları)
Lisans	Açık kaynak (Apache 2.0)	Ticari

İş akışı karşılaştırması

swagger-codegen iş akışı

1. Java 11 veya daha yenisini yükleyin.
2. openapi-generator-cli JAR dosyasını indirin.
3. java -jar openapi-generator-cli.jar generate -i spec.yaml -g delphi -o ./out komutunu çalıştırın.
4. Üretilen .pas dosyalarını IDE'nizde açın. Indy çalışma zamanı yolunu ekleyin. Delphi sürümünüz için derleme sorunlarını düzeltin. Null yapılabilir işlemeyi yamayın. Her spec değişikliğinden sonra yeniden çalıştırın.
5. Üretilen istemci, şablon tarafından gönderilen ayrı bir çalışma zamanı destek birimine bağlıdır. Bu birimi projenizle birlikte gönderirsiniz.

sgcOpenAPI iş akışı

1. sgcOpenAPI IDE'sini açın veya CLI'yi çağırın: sgcOpenAPI.exe -i spec.yaml -o ./out.
2. Üretilen birimi IDE'de açın. sgcWebSockets kullanıyorsanız zaten sahip olduğunuz TsgcHTTPComponentClient bileşenini kullanır.
3. Üretilen istemci bileşenini bir forma bırakın, temel URL'yi ve kimlik bilgilerini ayarlayın ve türlenmiş metotları çağırın.

Yan yana: üretilen bir GET /users/{id} metodu

Aynı OpenAPI parçası, her iki araç, aynı işlem. Yardımcıların adları ve tam biçimlendirme, açıklık için biraz stilize edilmiştir, ancak yaklaşımdaki farklar gerçektir.

swagger-codegen (Delphi hedefi, basitleştirilmiş)

function TUsersApi.GetUserById(const Id: Int64): TUser;
var
  HttpRequest: TIdHTTP;
  Path, Response: string;
  JsonValue: TJSONValue;
begin
  Path := StringReplace(BasePath + '/users/{id}', '{id}', IntToStr(Id), [rfReplaceAll]);
  HttpRequest := TIdHTTP.Create(nil);
  try
    HttpRequest.Request.CustomHeaders.AddValue('Authorization', 'Bearer ' + FApiKey);
    Response := HttpRequest.Get(Path);
  finally
    HttpRequest.Free;
  end;
  JsonValue := TJSONObject.ParseJSONValue(Response);
  try
    Result := TUser.Create;
    Result.Id := (JsonValue as TJSONObject).GetValue<Int64>('id');
    Result.Name := (JsonValue as TJSONObject).GetValue<string>('name');
    // ... nullable fields handled inconsistently ...
  finally
    JsonValue.Free;
  end;
end;

sgcOpenAPI

function TsgcUsersApiClient.GetUserById(const aId: Int64): TsgcUser;
var
  vResponse: TsgcAPIResponse;
begin
  Result := nil;
  vResponse := DoGet(Format('/users/%d', [aId]));
  Try
    if vResponse.StatusCode = 200 then
      Result := TsgcUser.FromJSON(vResponse.Content);
  Finally
    vResponse.Free;
  End;
end;

// TsgcUser is generated with typed nullable fields:
//   property Id: Int64 read FId write FId;
//   property Name: string read FName write FName;
//   property Email: TsgcNullable<string> read FEmail write FEmail;
//   property CreatedAt: TDateTime read FCreatedAt write FCreatedAt;
//
// Authentication, retry, HTTP/2, TLS are configured on the
// underlying TsgcHTTPComponentClient once, not per-method.

Dikkate değer farklar:

• sgcOpenAPI, taşımayı (bileşen düzeyindeki ayarlar) işlemlerden (türlenmiş metotlar) ayırır; böylece kimlik doğrulama, yeniden deneme ve TLS bir kez yapılandırılır.
• Null yapılabilir alanlar, “yok”, “null” ve “değer” arasında ayrım yapan türlenmiş bir TsgcNullable<T> sarmalayıcısı kullanır; bu, OpenAPI 3.x semantiğiyle eşleşir.
• Tarih/saat alanları, daha sonra ayrıştırdığınız bir dize değil, doğru ISO 8601 ayrıştırıcısıyla gerçek TDateTime kullanır.
• Üretilen istemci, sunucu ALPN aracılığıyla bildirirse HTTP/2'yi şeffaf bir şekilde destekleyen sgcWebSockets HTTP bileşenini kullanır.

Sunucu saplamaları

Her iki araç da sunucu tarafı kod üretebilir, ancak openapi-generator içindeki Delphi sunucu şablonları bu yazı yazıldığında minimaldir. sgcOpenAPI, işlem başına bir sanal metot, istek doğrulaması, yanıt biçimlendirme ve yerleşik bir OpenAPI gezgini uç noktasına sahip TsgcWebSocketHTTPServer tabanlı bir işleyici üretir. Tek bir Delphi projesinin API'yi açığa çıkarmasını ve bir Delphi istemcisinin onu tüketmesini istediğiniz dahili hizmetler için gidiş dönüş çok kısadır.

swagger-codegen'in hâlâ doğru seçim olduğu durumlar

• Birçok dilde zaten openapi-generator üzerinde standartlaştınız ve CI hattınızda tek bir araç istiyorsunuz.
• Spec'iniz küçük ve kararlı ve OpenAPI 3.1 özelliklerine ihtiyacınız yok.
• Üretilen Delphi kodunu hedef sürümünüze uydurmak için yamamaktan rahatsınız.
• Lisans nedenleriyle ticari yazılım kullanamıyorsunuz.

sgcOpenAPI'nin gerçekten zaman kazandırdığı durumlar

• Bu yazı yazıldığında swagger-codegen Delphi şablonunun sorunlu olduğu güncel bir Delphi sürümündesiniz (D11 / D12 / D13).
• Spec'iniz OpenAPI 3.1, oneOf / discriminator, null yapılabilir alanlar, dosya yüklemeleri veya eşzamansız akış kullanıyor.
• sgcWebSockets'i zaten kullanıyorsunuz ve tutarlı bir bileşen modeli ile tek bir HTTP yığını istiyorsunuz.
• HTTP/2, TLS, OAuth2 ve yeniden denemenin, üretilen istemciyi yeniden yazmadan “sorunsuz çalışmasına” ihtiyacınız var.

Son düşünceler

OpenAPI'den kod üretimi, bir projenin ömrü boyunca bileşik şekilde artan o üretkenlik kazanımlarından biridir; yeter ki üreteç, spec ve Delphi sürümünüzle uyumlu kalsın. swagger-codegen / openapi-generator mükemmel çok dilli araçlardır, ancak Delphi hedefleri tarihsel olarak en iyi çaba olarak ele alınmıştır. sgcOpenAPI, derlenebilir, deyimsel, tam özellikli OpenAPI 3.0 / 3.1 istemcilerini (ve sunucu saplamalarını) Java bağımlılığı olmadan ve elle yama döngüsü olmadan sunan, odaklanmış, yerel bir Delphi alternatifidir. REST API'lerini zaten entegre eden çoğu Delphi ekibi için, bir satıcı spec'ini ilk güncellediğinde kendini amorti eder.