SSS
Smarter by Design.Simpler for Business
TR7Enterprise Application Delivery & Security Platform

Türkçe

English

Türkçe

English

Görünüm

İleri

OpenAPI / Swagger dosyamdan otomatik kural üretebilir miyim? ​

Kısa cevap

Evet. Page Types ekranındaki Import (OpenAPI), OpenAPI 3 ya da Swagger 2.0 belgesini (.json, .yaml, .yml) okuyup her path için bir sayfa tipi üretir: path şablonları (/pet/{petId}) tek segmenti karşılayan * ile glob kurala dönüşür (/pet/*), Allowed Methods belgedeki operasyonlardan oluşur, Path Length 1–8192, Path Depth en çok 256 ve OWASP açık gelir; query ve header parametreleri izinli listelere (bütün operasyonlarda required olanlar zorunlu listeye), JSON, XML ve form gövde şemalarının yalnızca üst düzey alanları ilgili Check Fields bölümlerine yazılır; iç içe nesneler ve minimum/maximum aktarılmaz, gövdedeki required yalnızca form gövdesinde zorunlu alan olur (belgenin kurallara dönüştürülmesi). Cookie parametreleri ve servers adresleri kullanılmaz. İçe aktarma birleştirir: aynı path'li kural belgeden üretilenle değişir, belgede olmayan kurallar korunur, üçüncü taraf belge Any Paths'e dokunmaz. Motorun desteklemediği şema desenleri düşürülüp uyarı olarak bildirilir. Tersi için Export (OpenAPI) kural setini OpenAPI belgesi olarak indirir.

Sorun: API Kurallarını Elle Yazmak Uzun Sürüyor ​

Bir API'nin onlarca uç noktası için izinli metot ve parametre kuralları gerekiyor; uygulamanın OpenAPI tanımı zaten mevcut ve öğrenme için trafik beklenmek istenmiyor. Tanımda yer almayan path'lere gelen istekler Any Paths kuralıyla denetlenmeye devam eder.

Çözüm: İki Yöntem ​

DurumunuzUygun yöntem
Belgeden kural üretmekYöntem 1: Import (OpenAPI)
Kural setini OpenAPI belgesi olarak almakYöntem 2: Export (OpenAPI)
Kural setini birebir yedeklemek ya da tam değiştirerek taşımakJSON Export / Import → Bir host group'un kural setini JSON olarak dışa aktarıp başka bir ortama taşıyabilir miyim; hangi ayarlar bu dosyaya girmez?
  • Nasıl çalışır Belgedeki her path bir sayfa tipine dönüştürülür ve host grubunun mevcut listesiyle birleştirilir.
  • Nerede açılır Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → host grubunun mod kartı → N page types → Import (OpenAPI)
  • Gereksinim OpenAPI 3 ya da Swagger 2.0 belgesi (.json, .yaml, .yml); vService'te WAF koruması etkin
  • vService tipi WAF koruması etkin HTTP vService

Adım adım yapılandırma ​

1
Adım 1 Page types sekmesini aç

Left Monitor Panel'de WAF-Protected vServices sekmesinde vService'e tıklanır, WAF Management sekmesi açılır ve API'nin bulunduğu host grubunun mod kartı altındaki N page types satırına tıklanır (ekrana erişim).

2
Adım 2 Yedek al

Belgedeki path'lerle aynı path'li mevcut kurallar değiştirileceğinden önce Export ile grubun kural seti indirilir.

3
Adım 3 Belgeyi seç

Araç çubuğundaki Import (OpenAPI) tıklanır ve dosya seçiciden .json, .yaml ya da .yml belgesi seçilir (içe aktarma adımları).

4
Adım 4 Onayla

Are you sure? sorusunda Yes tıklanır. İşlem bitince OpenAPI import: N path applied bildirimi kaç path'in uygulandığını gösterir; dönüştürme uyarısı varsa bildirim uyarı (sarı) türünde gösterilir ve ilk sekiz uyarıyı listeler. Kurallar ayrı bir dağıtım adımı olmadan uygulanır; cluster kurulumunda varsayılan auto-sync ile eş cihaza da gönderilir, Manual Sync Mode açıksa Synchronize ile elle gönderilir.

Sonucu gözden geçirmek

Şablon parametreli path'ler listede glob kural olarak vurgu rengiyle görünür. Kurala tıklanınca detay panelinin Path sekmesinde Allowed Methods, Query ve Header sekmelerinde izinli ve zorunlu listeler görülür. Uyarıda düşürüldüğü bildirilen desenlerin ait olduğu alanlar desensiz kalır; gerekirse ilgili sekmeden düzenlenir. Belge birebir uygulamayı yansıtmayabileceğinden yeni kurallar önce host grubu Monitor modundayken gerçek trafikle denenir (OpenAPI tanımımdan API koruma kurallarını otomatik oluşturabilir miyim?).

Doğrulama ​

1ListeTR7 tarafı

Page types listesine ve mod kartındaki N page types sayısına bakılır.

BeklenenBelgedeki path'ler listede (ör. /pet/*)
2Detay paneliTR7 tarafı

Bir API kuralına tıklanıp detay panelinin Path ve Query sekmelerine bakılır.

BeklenenBelgedeki metotlar ve parametreler

Yöntem 2: Export (OpenAPI) ​

  • Nasıl çalışır Host grubunun kural seti OpenAPI 3 belgesi olarak indirilir; TR7, kendi ürettiği belgeyi Import (OpenAPI) ile kayıpsız geri okur.
  • Nerede açılır Page types → Export (OpenAPI)
  • Gereksinim vService'te WAF koruması etkin
  • vService tipi WAF koruması etkin HTTP vService

Adım adım yapılandırma ​

1
Adım 1 Page types sekmesini aç

WAF Management sekmesinde host grubunun N page types satırına tıklanır.

2
Adım 2 Belgeyi indir

Araç çubuğundaki Export (OpenAPI) tıklanır; onay sorulmaz, belge .json olarak iner. Glob path'ler {param} şablonuna, metotlar ve parametreler OpenAPI alanlarına çevrilir; tam kural tanımı ve Any paths yapılandırması belgenin TR7'ye özel x-tr7-waf bölümünde taşınır (üretilen belge). Bu belge Import (OpenAPI) ile yüklendiğinde kurallar kayıpsız gelir ve Any paths belgedekiyle değişir.

Doğrulama ​

1Belgeİstemci tarafı

İndirilen belgenin paths bölümüne bakılır.

BeklenenHer sayfa tipi bir path; glob'lar {param} şablonunda

Sık Yapılan Hatalar ​

  • Güncel olmayan belge kullanmak. Belgede olmayan uç noktalar ayrı kural almaz ve Any paths ile denetlenir.
  • Cookie ve path parametrelerinin ayrı denetim alacağını beklemek. Path parametreleri glob'un * bölümüne dönüşür; cookie parametreleri işlenmez; servers ön eki path'lere eklenmez.
  • Uyarıları okumamak. Düşürülen şema desenleri, ilgili alanı desensiz bırakır.
  • Import (OpenAPI)'yi tam değiştirme sanmak. JSON Import tam değiştirir; Import (OpenAPI) birleştirir (Import yaptığımda mevcut kurallar ne olur (tam değiştirme)?).
  • Yedeksiz içe aktarmak. Aynı path'li kuralların üzerindeki elle yapılmış ayarlar belgeden üretilenle değişir; önce Export alınır.

Dokümantasyonda nasıl yapılır

İlgili sorular