OpenAPI sözleşmesi ve destek kapsamı

Bu başvuru, sözleşme biçimini ve Lunex’te çalışan kapsamı açıklar. Model tekrar kullanımı ve değişiklik etkisi için tasarım kararlarına, belirli bir ayarın etkisi için sorular ve çalışma ipuçlarına geçebilirsiniz. Bu iki sayfa soldaki OpenAPI ve tasarım başlığının altındadır.

OpenAPI, HTTP API’nizin makine tarafından da okunabilen açıklamasıdır. İstemci hangi işlemleri çağırabileceğini, hangi veriyi göndereceğini ve hangi yanıtları bekleyebileceğini bu belgeden öğrenir. Lunex’te belge aynı zamanda çalışan HTTP işlemlerinin kaynağıdır; route’lar her operation’ın iş mantığını sağlar.

Sözleşmenin bölümlerini okuyun

Alan	Görevi	Neyi değiştirmez?
`openapi`	Belgenin OpenAPI standardı sürümü; örneğin `3.1.0`	Uygulamanın veya API’nizin ürün sürümü değildir.
`info.title` / `info.description`	API’nin adını ve amacını açıklar	Proje kimliğini veya çağrı adresini değiştirmez.
`info.version`	Sizin verdiğiniz API belge/sürüm etiketi	Yeni URL, ayrı deployment veya sürüm yönlendirmesi oluşturmaz.
`servers`	Runtime içinde API’nin bağıl taban yolunu belirler	Kurulumun DNS adını veya HTTPS sertifikasını hazırlamaz.
`paths`	Yolları, yöntemleri ve operation’ları içerir	İş route’larını kendiliğinden oluşturmaz.
`operationId`	Operation’ı tanımlar ve `direct:<operationId>` girişine bağlar	Route ID veya dosya adı değildir.
`parameters` / `requestBody`	Girdileri ve kabul kurallarını belirtir	Veriyi hedef sisteme dönüştürmez.
`responses`	Beklenen durumları, gövdeleri ve header’ları açıklar	Yanıtı üretmez ve otomatik response doğrulamasını etkinleştirmez.
`components`	Tekrar kullanılacak şema ve diğer tanımları tutar	Kullanılmayan bir component tek başına operation oluşturmaz.
`securitySchemes` / `security`	İstemcinin beklenen kimlik doğrulama biçimini açıklar	Dış erişim politikasını uygulamaz; API access ayrıca ayarlanır.

Örneğin info.version değerini 2.0.0 yapmak, /api/orders adresini /api/v2/orders yapmaz. Yol değişikliği gerekiyorsa servers veya paths alanını düzenleyin, route bağlarını kontrol edin ve değişikliği ilgili runtime’a uygulayın.

OpenAPI’nin alan tanımları için OpenAPI 3.1.1 belirtimi kullanılabilir. Aşağıdaki tablo, Lunex’te çalıştırabileceğiniz kapsamı açıklar.

Düzenleme, hazırlık ve çalışma farklı kontrollerdir

Form, sık kullanılan alanları görsel olarak düzenler. Source, bütün JSON belgesini gösterir. Formda ayrı kontrolü bulunmayan bir alan Source’ta tutulabilir. Ancak geçerli bir OpenAPI belgesi olması, her özelliğin Lunex runtime’ında çalıştırılabileceği anlamına gelmez.

Save belge tanılamasını ve bekleyen alan düzenlemelerini kontrol eder. Run/Reload/Build çalıştırma desteğini ve Direct bağlarını kontrol eder. Gerçek istek geldiğinde ise desteklenen request kuralları uygulanır. Örneğin bir response schema’sını düzenleyip kaydedebilirsiniz; bu, gerçek yanıtın schema’ya göre otomatik denetlendiği anlamına gelmez.

Çalıştırma desteği

Konu	Lunex’teki kapsam	Hazırlarken yapacağınız işlem
Belge biçimi	Projede `openapi.json`; JSON OpenAPI 3.0.x / 3.1.x	Swagger 2.0 veya YAML belgesini yüklemeden önce uygun JSON OpenAPI biçimine dönüştürün ve gözden geçirin.
Taban adresi	`servers` yoksa kök yol; tek bağıl sunucu yolu, `/` veya `/api` gibi	Tam URL, birden çok sunucu, path/operation düzeyinde server override kullanmayın.
Yöntemler	GET, POST, PUT, PATCH, DELETE	HEAD, OPTIONS veya TRACE iş işlemlerini bu runtime için tanımlamayın.
Operation bağı	Her benzersiz `operationId` için tam bir Direct consumer	İsim İngilizce harf veya `_` ile başlasın; devamında İngilizce harf, rakam, `_`, `.` veya `-` kullanın.
Girdiler	Path/query/header içinde tekil string, integer, number, boolean	Query için form, path/header için simple gösterim kullanın; karmaşık veriyi JSON body’ye taşıyın.
İleri parametre biçimleri	Cookie, array/object parametreleri, parameter `content`, farklı stiller ve `allowReserved` desteklenmez	İçe aldığınız sözleşmede bu alanları inceleyin.
Request body	POST/PUT/PATCH/DELETE; sözleşmede bildirilen media type’lar	JSON doğrulaması ile XML/metin iş doğrulamasını ayrı tasarlayın.
Referanslar	Belge içindeki çözümlenebilir yerel referanslar	Başka dosya veya URL’ye giden `$ref` tanımlarını belge içine toplayın.
JSON request şemaları	Türler, zorunlu alanlar, sınırlar, enum, array/object ve desteklenen birleşimler	Şema kurallarını kullanın; unsupported hatasını çalıştırmadan önce giderin.
İleri request şemaları	Recursive/boolean schema, özel dialect ve bazı ileri anahtarlar desteklenmez	Çalıştırma hatasının gösterdiği tanımı sadeleştirin veya iş kontrolünü route’ta yapın.
Yanıtlar	Kod, media type, schema, örnek ve header tanımları	Gerçek yanıtı route’ta üretin ve sözleşmeyle karşılaştırın.
Güvenlik tanımları	Sözleşmede açıklanabilir	Basic/API key/JWT uygulamasını API access ile kurun.

Authorization, Content-Type ve Accept gibi taşıma/güvenlik header’larını sıradan bir özel header parametresi gibi modellemeyin. Gövde ve yanıt biçimini media type alanlarında, kimlik doğrulamayı güvenlik tanımında belirtin. Try it ilgili biçimler için ayrı alanlar sunar; gateway kimliğini yayımlanmış adreste sınayın.

Sözleşmeyi içe alın ve inceleyin

JSON OpenAPI 3.0/3.1 dosyasını openapi.json adıyla hazırlayın. Dış referansları belge içine alın; örnek metinlerde geçen sıradan $ref değerlerini değiştirmeyin.
Projede openapi.json yoksa Source → Files → Upload üzerinden yükleyip Save and view seçin. Dosya varsa API design → Source içinde içeriğini düzenleyin; Upload aynı adlı dosyanın üzerine yazmaz. Mevcut sözleşmenin farkını API actions → Compare with Git ile inceleyebilirsiniz.
API design → Form üzerinden operation listesini kontrol edin. Hata bağlantılarını izleyerek belge ve referans sorunlarını düzeltin.
servers, yöntemler, parametre biçimleri, operation ID’leri ve request şemalarını yukarıdaki çalışma desteğiyle karşılaştırın.
Her operation için direct:<operationId> route’unu ekleyin. Dışarıdan alınan sözleşme bu iş mantığını içermez.
Save → Run/Reload sonrasında gerçek istekleri deneyin. Başarı örneğinin yanında eksik veya geçersiz girdi de gönderin.

Bir URL’den otomatik sözleşme içe alma adımı kullanmıyorsunuz; yükleme dosya üzerinden yapılır. Başka isimli JSON dosyası projenin ana API sözleşmesinin yerini almaz.

Sözleşmeyi tüketiciye verin

Source → Files → openapi.json → Download source ile belgeyi indirin. Alıcıya hangi ortamın adresini kullanacağını, seçilen kimlik doğrulamayı, örnek çağrıyı ve beklenen sonucu da verin. Dosyadaki /api gibi bağıl server yolu, müşterinin bağlanacağı gerçek origin ve proje ön ekini tek başına belirtmez.

Belgeyi bir HTTP istemcisine veya kod üretme aracına aktardığınızda o aracın OpenAPI sürüm desteğini kontrol edin. Lunex sözleşmeyi sağlar; başka aracın ürettiği istemcinin davranışını gerçek çağrılarla doğrulayın. Örnekler ve açıklamalar paylaşılabilir gösterim verisi içermeli; Secret değerlerini sözleşmeye koymayın.

Sözleşmeyi değiştirmeden önce etkiyi görün

Değişiklik	Etkilenen kullanım
Bir path veya yöntem değişir	İstemcinin çağrı adresi/yöntemi güncellenmelidir.
`operationId` değişir	Direct girişi güncellenmelidir; aynı path’in başka iş mantığına bağlanması mümkündür.
Ortak request schema’sına zorunlu alan eklenir	O schema’yı kullanan bütün işlemler artık yeni alanı bekler.
Maximum küçülür veya enum seçeneği kaldırılır	Daha önce kabul edilen bazı istekler reddedilir.
Response alanı yeniden adlandırılır	Alanı okuyan istemciler ve route’un gerçek çıktısı birlikte incelenmelidir.
Örnek veya açıklama değişir	Dokümantasyon ve Mock beklentisi değişir; route iş mantığı değişmez.
Yalnızca `info.version` değişir	Belge etiketi değişir; ek endpoint veya ikinci çalışan sürüm oluşmaz.

Yeni sürüm tasarımınız farklı istemcileri etkileyecekse yeni yolu ve geçişi açıkça planlayın. Bir sürüm etiketi yazmak bunları otomatik yönetmez. Değişiklikleri önce çalışan örnekte, sonra ilgili yayınlama adımlarıyla doğrulayın.