sgcOpenAPI 2026.9.0, ürünün bugüne kadarki en büyük sürümü. Kendinden önceki sürüm, çoğu eğitimin gösterdiği biçimdeki belirtimleri işliyor, geri kalan her şeyde sessizce bozuluyordu. Bu sürümde ayrıştırıcı, özellik özellik, OpenAPI 3.0, 3.1 ve 3.2 belirtimlerine ve gerçekten yayımlanmış belgelere karşı gözden geçirildi. Sonuç, 9 yeni özellik, düzeltilmiş 26 hata ve bilinçli olarak yapılmış 5 kırıcı değişiklik.
Kısacası, daha önce derlenmeyen kod üreten, daha kötüsü derlenip yanlış URL'yi çağıran kod üreten belirtimler için üretilen istemci artık doğru.
Ayrıştırıcı Artık Yapamadığı Şeyi Size Söylüyor
Eski ayrıştırıcının sorun bildirmek için tek bir yolu vardı, bir istisna oluşturmak, geri kalan her şeyi ele almak için de tek bir yolu vardı, sessizce devam etmek. Üretemediği bir işlem çıktıda basitçe yer almıyordu ve bunu ancak orada olmayan bir metodu ararken fark ediyordunuz.
Artık her belge bir Warnings listesiyle birlikte geliyor. Eksik bir openapi veya info üyesi, yanlış JSON türüne sahip bir üye, üretilemeyen bir işlem, çözümlenemeyen bir path item referansı ve okunan ama henüz uygulanmayan bir JSON Schema anahtar sözcüğü, hepsi orada kaydediliyor. Liste her okumada temizleniyor, dolayısıyla elinizdeki liste az önce ayrıştırdığınız belgeye ait.
uses
sgcOpenAPI_Classes, sgcOpenAPI_Parser_Client_Pascal;
var
oParser: TsgcOpenAPI_Parser_Client_Pascal;
i: Integer;
begin
oParser := TsgcOpenAPI_Parser_Client_Pascal.Create;
Try
oParser.OpenAPIClassName := 'TPetStoreClient';
oParser.OpenAPINamespace := 'PetStore';
oParser.OutputFileName := 'PetStoreClient.pas';
oParser.ReadFromFile('petstore.json');
for i := 0 to oParser.Warnings.Count - 1 do
Memo1.Lines.Add('warning: ' + oParser.Warnings[i]);
oParser.SaveToFile('PetStoreClient.pas');
Finally
oParser.Free;
End;
end;
Kaydetmeden önce OutputFileName değerini ayarlayın. Bir Pascal birimi yalnızca bildirilen adı dosyasının temel adıyla eşleştiğinde derlenir ve üreteç birimi girdi belgesine göre adlandırıyordu, bu yüzden petstore.json dosyasından MyClient.pas üretmek, derlenmeyen petstore adlı bir birim ortaya çıkarıyordu. Artık çıktı adı geçerli.
Hangi Sürümü Okuduğunu Biliyor
OpenAPI 3.0 ve 3.1, aynı adı taşıyan anahtar sözcükler konusunda anlaşamıyor ve eski ayrıştırıcı her belgeyi 3.0 gibi ele alıyordu. En açık örnek exclusiveMinimum, 3.0'da minimum üzerinde bir boolean değiştirici, 3.1'de ise kendi başına bir sayı. Birini diğeri gibi okumak sınırı yanlış belirler.
Sürüm artık bir lehçe olarak ayrıştırılıyor, Dialect, DialectMajor ve DialectMinor olarak sunuluyor ve farklılık gösteren her anahtar sözcük kendi sürümünün gerektirdiği şekilde okunuyor.
oParser.ReadFromFile('api.yaml');
case oParser.Dialect of
oapiDialect30: ShowMessage('OpenAPI 3.0');
oapiDialect31: ShowMessage('OpenAPI 3.1');
oapiDialect32: ShowMessage('OpenAPI 3.2');
end;
Bunun üzerine 3.1, webhooks, jsonSchemaDialect ve components.pathItems öğelerini, lisans identifier alanını, mutualTLS güvenlik şemasını, ["string","null"] gibi bir dizi olarak bildirilen bir türü ve düz bir boolean olarak bildirilen bir şemayı getiriyor. Hepsi destekleniyor. Kod üretecinin henüz işlemediği JSON Schema 2020-12 anahtar sözcükleri modele okunuyor ve Warnings üzerinden bildiriliyor, böylece eksik olan kısım görünmez olmak yerine görünür oluyor.
3.2'den itibaren ayrıştırıcı query işlemini ve additionalOperations eşlemesini destekliyor. Bunlardan birini bildiren bir yol artık eşleşen metotları üretiyor, bunlar bir X-HTTP-Method-Override başlığı taşıyan POST olarak gönderiliyor.
Yol Düzeyindeki Parametreler
Bu, çoğu kullanıcının hissedeceği düzeltme. Belirtim, bir parametreyi altındaki her işlemde tekrarlamak yerine path item üzerinde bir kez bildirmenize izin verir, belirtimin önerdiği ve çoğu kamuya açık belgenin kullandığı biçim de budur. Eski ayrıştırıcı bu parametreleri okuyor, sonra da atıyordu.
Üretilen metot hiç argüman almıyordu ve istek, yer tutucu URL'de hâlâ dururken, birebir /pets/{petId} olarak gidiyordu. İlk çağrı 404 ile dönene kadar çalışan bir istemci gibi görünüyordu.
Birleşebilen Şemalar
Bileşim, eski ayrıştırıcının en zayıf yanıydı ve her dalı farklı bir biçimde yanlıştı. allOf, birden çok temel şemadan yalnızca sonuncusunu tutuyor, diğerlerinin üyelerini atıyordu. oneOf, her dalı tek bir sınıfta birleştiriyor, bu da yinelenen alanlar üretiyordu. anyOf hiç ele alınmıyor ve bir string'e çözümleniyordu. Hem properties hem additionalProperties bildiren bir şema, bütün özelliklerini kaybediyordu.
Dördü de artık belgenin tarif ettiği şeyi üretiyor. Satır içi bir nesne şeması da string'e düşmek yerine kendi sınıfını alıyor ve items eksiksiz bir şema olarak okunuyor, böylece satır içi nesnelerden oluşan bir dizi, enum'lardan oluşan bir dizi ve iç içe bir dizi, her biri doğru türü üretiyor.
Sunucunun Beklediği Değeri Taşıyan Enum'lar
Üretilen enum tabloları, aktarımda kullanılan değer yerine temizlenmiş Pascal tanımlayıcısını içeriyordu, bu yüzden allow-all değeri allowall, json-file değeri de jsonfile olarak gidiyordu. Bu enum'lardan biriyle kurulan her istek reddediliyordu.
Tablolar artık gerçek değeri taşıyor, belirtimdeki bildirim sırası korunuyor, tam sayı enum'ları da bir tablo alıyor ve fazladan bir Unknown üyesi üretiliyor, böylece sunucunun sonradan eklediği bir değer sessizce listenin ilk üyesi olarak çözülmüyor.
Özellik adları aynı işlemi diğer yönden görüyor. property, class, string veya function gibi bir Delphi ayrılmış sözcüğüyle adlandırılan bir şema özelliği ya da yalnızca büyük küçük harfle ayrılan Name ve name gibi iki özellik, derlenmeyen bir birim üretiyordu. Özellik artık yeniden adlandırılıyor ve asıl ad bir JSONName özniteliğiyle korunuyor, böylece serileştirme belgeyle eşleşmeye devam ediyor.
Yanıtlar, Yalnızca Bir Kez Bildirdikleriniz Dahil
default yanıtı ile 2XX, 4XX ve 5XX aralık yanıtları sessizce atılıyordu. Hatalarını yalnızca default üzerinden bildiren bir API, ki bu yaygındır, hiç türlenmiş hatası olmayan bir istemci üretiyordu. Artık okunuyorlar. Birden çok başarılı yanıt bildirildiğinde en düşük olanı kullanılıyor ve bir işlem birden çok ortam türü sunduğunda application/json tercih ediliyor.
Aktarımdaki Parametreler
Üretilen istemci artık cookie parametrelerini ve eksiksiz OpenAPI parametre serileştirme kurallarını destekliyor: matrix, label, simple, form, spaceDelimited, pipeDelimited ve deepObject, her biri explode ve allowReserved ile birlikte. Yeni AddArray ve AddObject metotları, gerektiğinde yapılandırılmış değerleri elle kurmanızı sağlıyor.
// query parameters built with the serialization style the document declares
oRequest.AddArray('tags', ['dog', 'cat'], True); // explode
oRequest.AddObject('filter', ['color', 'red', 'size', 'M']);
Dış Referanslar
Dosyalara bölünmüş bir belirtim ancak kısmen çalışıyordu. ./common.yaml#/components/schemas/Error gibi bir JSON Pointer parçası taşıyan bir referans çözümlenemiyordu. Birbirine referans veren iki dosya ayrıştırıcıyı çökertiyordu. Bir alt belgenin içindeki göreli bir referans, kendi dosyasına göre değil kök belgeye göre çözümleniyordu. Aynı temel ada sahip iki dış dosya birbirinin üzerine yazıyor ve ana belgeye ait bir şemanın yerini alabiliyordu. Ayrıca bir referans zinciri tam olarak bir adım izleniyordu.
Bunların hepsi düzeltildi ve bir şey de bilinçli olarak sıkılaştırıldı: bir dış referans daha önce makinedeki herhangi bir dosyayı, ../../../credentials.json dahil, okuyabiliyor ve içeriği üretilen birime kopyalayabiliyordu. Dış referanslar artık ana belgenin dizini ile sınırlı. Bir yerleşim gerçekten de dışarıya uzanmayı gerektirdiğinde, bu sınırlama açıkça kaldırılıyor.
uses
sgcOpenAPI_Bundle;
begin
// off by default: references may not leave the folder of the main document
sgcOpenAPIAllowRefsOutsideRoot := True;
end;
Tam Olarak UTF-8 Olmayan Dosyalar
RFC 8259, bir JSON belgesinin UTF-8 olduğunu söyler, yayımlanmış belirtimlerin epeycesi ise değildir. Bayt sırası işareti taşıyan bir dosya, ASCII dışında herhangi bir karakter içerdiği anda UTF-8 hatasıyla reddediliyordu ve Çince veya Japonca metin sessizce soru işaretleriyle değiştiriliyordu.
Geçerli UTF-8 olmayan bir belge artık başarısız olmak yerine, bir uyarı kaydedilerek Windows-1252 olarak okunuyor. Bayt sırası işareti taşıyan bir UTF-16 dosyası doğru okunuyor. Üretilen dosya açık bir kodlamayla yazılıyor ve hedef kodlamanın temsil edemediği bir karakter, sessizce soru işaretine dönüşmek yerine bildiriliyor.
Derleme Betiğine Koyabileceğiniz Bir Komut Satırı
Komut satırı artık bir çıkış kodu belirliyor: başarıda 0, farklı hatalar için 1'den 7'ye kadar, böylece bir derleme adımı üretimin çalışıp çalışmadığını anlayabiliyor. Hata mesajları her zaman standart hataya gidiyor ve -l anahtarı artık yalnızca ilerleme günlüğü için.
sgcOpenAPI -i petstore.json -o PetStoreClient.pas -c TPetStoreClient
if errorlevel 1 (
echo OpenAPI generation failed with exit code %errorlevel%
exit /b %errorlevel%
)
Bununla birlikte üç komut satırı hatası da gitti. Belgelenmiş -output anahtarı, birimi geçerli dizinde utput adlı bir dosyaya yazıyordu ve mesajlar bastırıldığı için çalışma yine de başarılı görünüyordu. Araç, konsol bağlı olmadan çalıştırıldığında, ki zamanlanmış bir görevde veya bir derleme aracısında durum tam olarak budur, hiçbir şey olmuyordu ve var olan bir çıktı yönlendirmesi atılıyordu. Ayrıca -h, etkinleştirilmemiş bir makinede kullanım metni yerine bir lisans hatası yazdırıyordu, -m veya -a için geçersiz bir değer sessizce kabul ediliyordu ve bilinmeyen bir anahtar yok sayılıyordu.
Bu sürümde yeni olarak -r (veya -remote), bir YAML veya Swagger 2.0 belgesini converter.swagger.io adresindeki kamuya açık dönüştürücü aracılığıyla dönüştürüyor. Varsayılan olarak kapalı, çünkü belgenizi üçüncü bir tarafa gönderiyor, dolayısıyla bilerek açtığınız bir şey.
Swagger 2.0 dönüşümünün kendisi, anılmaya değer iki biçimde bozuktu. Her sayı bir string'e dönüşüyordu, bu yüzden sayısal bir default değeri derlenmeyen bir birim üretiyor ve dönüştürülen belge geçerli bir OpenAPI 3.0 belgesi olmuyordu. Ayrıca orada düz bir string olan Swagger 2.0 discriminator alanı, geçersiz bir tür dönüşümüyle ayrıştırmanın tamamını sonlandırıyordu.
Kırıcı Değişiklikler
Beş değişiklik, yalnızca yükseltmenin ötesinde sizden bir karar gerektiriyor.
Üretilen istemciler artık sunucu sertifikasını doğruluyor. Daha önce doğrulamıyorlardı, bu da ortadaki adamın sunduğu bir sertifika dahil her sertifikayı kabul ettikleri anlamına geliyor. Kendinden imzalı veya test amaçlı bir uç noktaya erişmek için bunu bilinçli olarak kapatın.
oClient.TLSOptions.VerifyCertificate := False; // test endpoints only
// certificates are trusted through the OpenSSL default paths, so a machine
// with no certificate store configured needs an explicit root
oClient.TLSOptions.RootCertFile := 'cacert.pem';
İstek gövdesi UTF-8. RFC 8259'un gerektirdiği gibi. Bir sınıf artık boş bir string'i atlamak yerine "field": "" olarak serileştiriyor. Null değerler ayrıca denetleniyor.
oClient.JSONIgnoreEmptyStrings := True; // previous output
oClient.JSONIgnoreNullValues := True; // default
Bir yanıt, sağladığınız bir ResponseStream nesnesini artık serbest bırakmıyor. Eski davranış için OwnsResponseStream değerini True yapın. İstemciyi kendi OnResponse, OnError veya OnCancel işleyicisinin içinden serbest bırakmak, artık askıda kalmak yerine açık bir hata oluşturuyor.
Bir komut satırı anahtarının değeri -name value veya -name:value biçiminde yazılmalıdır. Ayırıcı içermeyen bitişik biçim, örneğin -x"GET /pets", artık kabul edilmiyor. -x anahtarının, -xml gibi x ile başlayan diğer anahtarlarla eşleşmesine yol açan da bu biçimdi.
Dizi olarak bildirilen bir parametre artık dizi olarak üretiliyor. Daha önce string olarak üretiliyordu, bu yüzden o işlemler için üretilen metodun imzası değişiyor.
Geri Kalan Her Şey
Kalan düzeltmeler, ancak canınızı yaktıklarında fark ettiğiniz türden. Beklenmeyen bir JSON türüne sahip bir üye, örneğin "properties": [], atlanmak yerine ayrıştırmayı geçersiz bir tür dönüşümüyle sonlandırıyordu. default değeri olmayan, tam sayı türündeki bir şemaya 0 varsayılanı veriliyor ve tek değerli bir enum sabit olarak ele alınıyordu, bu da parametreyi üretilen metottan tamamen çıkarıyordu. Aynı belgeyi iki kez okumak her yolu, etiketi, sunucuyu ve şemayı ikiye katlıyordu. Yolların arasına yerleştirilen x-tagGroups gibi bir belirtim uzantısı, bir yolmuş gibi okunuyordu. enum, required ve tags öğeleri virgülle ayrılmış bir metin yardımcısıyla ayrıştırılıyordu, bu yüzden virgül veya JSON kaçış dizisi içeren bir değer bölünüyor ya da bozuluyordu. Birden çok şema listeleyen bir güvenlik gereksinimi yalnızca ilkini tutuyor, hepsinin karşılanması gerektiği koşulunu kaybediyordu. info.contact ve info.license hiçbir zaman okunmuyordu, çünkü asla doğru olamayacak bir koşul vardı. Birden çok değişken içeren bir sunucu URL'si yanlış değeri yerine koyuyor ve bir liste indeksi hatası oluşturabiliyordu. Bir belirtimi paketlemek, girdi dosyasının üzerine yedek almadan ve hiçbir mesaj vermeden yazıyor ve belgedeki her tipografik kesme işaretini siliyordu. Ayrıca C:\My Specs\ gibi boşluk içeren bir yolda saklanan bir belirtim, dış referanslarını çözümleyemiyordu.
Nasıl Edinilir
sgcOpenAPI 2026.9.0 şimdi mevcut, tam kaynak kodu ve bir yıllık güncelleme ile birlikte. Delphi 7'den Delphi 13 Florence'a kadar olan sürümleri ve eşleşen C++ Builder sürümlerini destekliyor.
Ürün sayfası · Deneme sürümünü indirin · Değişiklik günlüğü
Sorularınız veya geri bildiriminiz mi var? Bize ulaşın, kodu yazan kişilerden yanıt alacaksınız.