Bu sayfa, DevUtilities ile tarayıcıda OpenAPI ve Swagger belgelerini lint etmek için kanonik kılavuzdur. Okurken yukarıya bir spesifikasyon yapıştırın veya aşağıdaki bir konuya atlayın. Doğrulama yerel kalır — belgeler asla yüklenmez. Lint yeşil olduğunda hazırlık skoru ve generate komutu önizlemesi için Kiota SDK Engine’e aktarın.

OpenAPI Validator, OpenAPI 3 ve Swagger 2 JSON/YAML için istemci tarafı bir linter’dır. SDK üretimi veya ağ geçidi içe aktarmadan önce engelleyicileri düzeltmeniz için yol bilinçli tanılarla VALID, VALID WITH WARNINGS veya INVALID bildirir.

Ne elde edersiniz

• OpenAPI 3.x ve Swagger 2 belgelerini (JSON veya YAML) ayrıştırır
• Durum bandı: VALID / VALID WITH WARNINGS / INVALID
• Sürüm anahtarları, paths kapsamı, servers ve yaygın yapısal sorunları kontrol eder
• Yalnızca yerel lint — dahili API spesifikasyonları için güvenli
• codegen hazırlığı için Kiota SDK Engine’e doğrudan aktarım yolu

Bu aracı şu durumlarda kullanın

• Microsoft Kiota veya diğer üreteçlerden önce hızlı bir ön kontrol gerekir
• CI veya bir PR kontrol listesi işlenmiş spesifikasyonun okunabilir lint’ini ister
• Swagger 2 dosyası miras aldınız ve OpenAPI 3 çalışmasından önce geçiş uyarıları istiyorsunuz
• Yinelenen operationId veya bozuk $ref codegen’i kırmaya devam ediyor

Şu durumlarda ilgili aracı tercih edin

• Tam Kiota hazırlık skoru, dil matrisi ve CLI oluşturucu gerekir → Kiota SDK Engine
• Yalnızca JSON yüklerini güzelleştirmek gerekir → JSON Formatter
• Sahte yanıt dizileri gerekir → JSON Generator

Kod üreteçleri (özellikle Kiota) gelişigüzel bir YAML bakışının kaçırdığı yapısal sorunlarda yüksek sesle başarısız olur. Önce burada lint edin, ardından üreteç özel hazırlık için Kiota SDK Engine’i açın.

codegen öncesi temizlenecek engelleyiciler

• Yinelenen veya eksik operationId (yöntem adı çakışmaları)
• Başarı durum kodlarında eksik veya boş responses
• components’e geçersiz veya kopuk $ref
• Eksik openapi/swagger sürüm anahtarı veya boş paths nesnesi
• Döngüsel schema başvuruları (çoğu zaman ardından Kiota’da görünür)

Erteleyebileceğiniz uyarılar

• Eksik servers[] — istemcilerin --base-url geçersiz kılmaları gerekebilir
• Swagger 2 geçiş notları — yeni API’ler için OpenAPI 3 tercih edin
• Seyrek açıklamalar — belgeleme kalitesi, ayrıştırma engelleyicisi değil

SDK üretmeden önce ilk adım adım tur.

1. Giriş paneline OpenAPI 3 veya Swagger 2’yi JSON veya YAML olarak yapıştırın.
2. Durumu okuyun: VALID, VALID WITH WARNINGS veya INVALID.
3. Tanı listesindeki her hatayı düzeltin — operationId, responses ve $ref hatalarından başlayın.
4. Durum VALID olana veya yalnızca kabul edilebilir uyarılar kalana kadar yeniden lint edin.
5. Temiz spesifikasyonu Kiota SDK Engine’e aktarın; skor, dil önizlemesi ve kiota generate komutu için.
6. Düzeltilmiş belgeyi işleyin ve isteğe bağlı olarak bu lint’i PR kontrol listesi öğesi yapın.

Çekme istekleri, daha sonra gece SDK yeniden üretimini bozan OpenAPI düzenlemelerini birleştirir. İnceleyenler yinelenen operationId’leri gözle göremez.

Bu araç bunu nasıl çözer

1. İnceleme sırasında PR’nin OpenAPI belgesini doğrulayıcıya yapıştırın.
2. Onaylamadan önce VALID (veya yalnızca belgelenmiş uyarılar) zorunlu kılın.
3. Tanı metniyle inceleme iş parçacığında yinelenen operationId ve bozuk $ref’leri belirtin.
4. Birleştirmeden sonra aynı belgeye karşı CI’da Kiota çalıştırın.

Üreteçlerin çarptığı aynı başarısızlık sınıfını yakalayan insan hızında lint kapısı — spesifikasyonu yüklemeden.

Bir ekip kiota generate çalıştırmak üzeredir ve belgenin adlandırma veya $ref sorunlarında başarısız olmayacağından emin olmak ister.

Bu araç bunu nasıl çözer

1. INVALID temizlenene kadar belgeyi burada lint edin.
2. Kiota SDK Engine’e aktarın ve OpenAPI Readiness skorunu inceleyin.
3. Kalan Kiota’ya özgü sorunları (döngüsel refs, nullable stili) Kiota tanılarında düzeltin.
4. Hazırlık kabul edilebilir olduğunda üretilen CLI komutunu kopyalayın.

İki adımlı yerel iş akışı: yapısal lint → Kiota hazırlığı → makinenizde generate.

Eski bir Swagger 2 JSON hâlâ bir ağ geçidini çalıştırıyor. Paydaşlar Kiota’yı benimsemeden önce OpenAPI 3 istiyor.

Bu araç bunu nasıl çözer

1. Swagger 2 belgesini yapıştırın ve geçiş uyarılarını not edin.
2. Her dönüştürücüyü engelleyecek yapısal INVALID sorunları düzeltin.
3. Yeni özellikler için OpenAPI 3 geçişi planlayın; yalnızca kapılı olduğu sürece Swagger 2’yi tutun.
4. Kiota’dan önce OpenAPI 3 sonucunu yeniden lint edin.

Swagger 2’nin uyarılarla ayrıştırıldığına dair net sinyal — yeni SDK işi için OpenAPI 3 tercih edin.

Üreteçler istemci yöntemlerini operationId’den adlandırır. Yinelenenler çakışmaya yol açar.

Neden olur

İki veya daha fazla işlem aynı operationId’yi paylaşır veya üretecin gerektirdiği yerde operationId eksiktir.

Tanılama

Belgede yinelenen operationId değerlerini arayın. Hem Kiota hem bu linter çakışmaları işaretler — SDK motorunu açmadan önce burada düzeltin.

Düzeltmeler

1. Her işleme benzersiz bir operationId atayın (fiil + kaynak yaygın bir kalıptır).
2. Düzenleme sırasında kopyalanan kullanılmayan yinelenen paths’leri kaldırın.
3. Kısmi bir SDK için kırparken üretim ID’lerini rastgele yeniden adlandırmak yerine çakışan paths’leri düşürün.

Yeniden adlandırdıktan sonra yeniden lint edin ve Kiota hazırlığını yeniden kontrol edin — önizlemelerdeki yöntem adları değişir.

Kullanılabilir responses olmayan işlemler tipli istemci üretimini bozar.

Neden olur

Bir path işlemi responses’ı atlar veya başarı responses’ında schema olmadan boş content {} vardır.

Tanılama

Her işlemin responses haritasında 200/201 (veya default) girişlerini inceleyin ve content şemalarının çözüldüğünden emin olun.

Düzeltmeler

1. application/json (veya ilgili) medya türü olan en az bir başarı response ekleyin.
2. content’i boş bırakmak yerine $ref ile components.schemas’a işaret edin.
3. İstemcilerin işlemesi gerektiğinde hata responses’ını (4xx/5xx) belgelendirin — atlanırsa uyarılar kalabilir.

Geçersiz $ref işaretçileri lint ve codegen sırasında şema çözümünü engeller.

Neden olur

Bir $ref eksik bir bileşeni hedefler, yanlış bir JSON Pointer kullanır veya çözücünün genişletemediği bir döngü oluşturur.

Tanılama

Başarısız her $ref yolunu components.schemas / parameters / responses içine izleyin. Hedef anahtarın var olduğunu ve yazımın eşleştiğini doğrulayın.

Düzeltmeler

1. Eksik bileşen hedefini onarın veya yeniden oluşturun.
2. $ref dizelerini #/components/... işaretçilerine normalleştirin.
3. Sığ DTO’lar çıkararak döngüsel başvuruları kırın (ardından Kiota’nın döngüsel-ref kılavuzu geçerlidir).

Belgeyi değiştirmeden önce bandı yorumlayın.

OpenAPI Validator ve Kiota SDK Engine birbirini tamamlar. Yapısal sağlığı burada lint edin; üreteç hazırlığı, dil matrisi, uç nokta seçimi ve CLI komutu dışa aktarımı için Kiota’yı kullanın.

• VALID’den sonra temiz spesifikasyonu Kiota SDK Engine’e aktarın veya yapıştırın.
• Yinelenen operationId, döngüsel $ref ve nullable stil sorunları için Kiota tanılarını kullanın.
• Kiota Generate adımından kiota generate’i kopyalayın — dosya çıktısı hâlâ yerel Kiota CLI ile çalışır.
• Her iki aracı istemci tarafında tutun ki dahili API sözleşmeleri tarayıcıyı asla terk etmesin.

• Onaylamadan önce her OpenAPI PR’de lint edin.
• Yeni API’ler için OpenAPI 3 tercih edin; Swagger 2’yi geçiş uyarılarıyla legacy sayın.
• operationId’yi benzersiz ve kararlı tutun — yeniden adlandırmalar üretilmiş istemcileri sarsar.
• Başarı responses’ına her zaman çözülebilir bir schema verin.
• Kiota’yı açmadan önce INVALID’i temizleyin; ardından üreteç özel hazırlık için Kiota’yı kullanın.
• Bu yerel yol yeterliyken dahili spesifikasyonları üçüncü taraf lint SaaS’a yüklemeyin.