oas-drift: OpenAPI spesifikasyonları ile Python kodu arasındaki sapmaları yakalayan bağımlılıksız bir CLI

OpenAPI sapmaları için bağımlılıksız bir denetleyici

Sunnydachs adıyla paylaşım yapan bir geliştirici, bir OpenAPI spesifikasyonunu bir Python kod tabanında fiilen mevcut olan route'larla karşılaştıran ve ikisinin nerede ayrıştığını raporlayan açık kaynaklı bir komut satırı aracı olan oas-drift'ı yayınladı. Dev.to'daki duyuruda yazar, bunu tanıdık bir başarısızlık senaryosuna bir yanıt olarak konumlandırıyor: SDK'lar, frontend tipleri, API dokümantasyonu ve mock sunucularının tümü spesifikasyondan üretildiği için, uygulama sessizce saptığında ondan üretilen her şey gizli biçimde yanlış hale gelir — üretilen bir client, sunucunun artık 405 ile yanıtladığı bir DELETE endpoint'ini çağırmaya devam edebilir.

Araç, bir OpenAPI 3.x JSON dosyası ile bir kaynak kök dizini alır ve ayrışmalıkları üç kategoriye ayırır: spesifikasyonda tanımlı ancak kodda eşleşen route'u olmayan endpoint'ler, kodda uygulanmış ancak spesifikasyonda bulunmayan route'lar ve path eşleşirken HTTP metodunun farklı olduğu durumlar. Tarama, bir dizine karşı --spec bayrağıyla salt okunur şekilde çalışır ve bir -- bayrağı betiklere uygun yapılandırılmış çıktı üretir.

Bir kapı değil, bir dedektör

Öne çıkan bir tasarım tercihi var: oas-drift, sapma bulsun ya da bulmasın çıkış kodu 0 ile çıkıyor. Yazara göre bu, bir dedektörü bir kapıdan ayıran şey. İlk temasta build'i kıran araçlar ertesi gün kaldırılmaya meyillidir ve hangi sapmanın önemli olduğu bir politika sorunudur — spesifikasyonda eksik olan bir /health endpoint'i genellikle zararsızdır, ama bir ödeme route'undaki metod uyumsuzluğu öyle değildir. Araç bu kararı kodlamak yerine raporlar ve kararı takımlara bırakır; zorlama isteyenler JSON raporunu CI'da jq'dan geçirebilir.

Uygulama güvenlik tarafında da temkinli. Kaynak dosyaları Python'ın ast modülüyle ayrıştırır ve hiçbir şey import etmez, çalıştırmaz veya yazmaz; bu da raporları deterministik tutar: aynı girdi aynı çıktıyı verir. Yalnızca Python 3.11+ standart kütüphanesi üzerinde çalışır; üçüncü taraf paket gerekmez ve dil modeli involved yoktur. Yazar, bunu bu ay yayımlanan diğer deterministik denetleyicilerle kardeş olarak nitelendiriyor; bunlara README'leri kodla karşılaştıran doc-drift de dahil.

Gerçek bir kod tabanında test edilmiş, literal path eşleştirmesi

Eşleştirme kuralı kasıtlı olarak katıdır: spesifikasyondaki /users/{id}, koddaki /users/{id} ile ve yalnızca onunla eşleşir. Router prefix'leri çözümlenmez; dolayısıyla bir prefix ile mount edilmiş bir FastAPI router'ı ve göreli bir route path'i, spesifikasyondaki tam nitelikli path ile eşleşmeyecektir. Yazar bunu, FastAPI'nin resmi full-stack-fastapi-template backend'i üzerinde doğruladı — 25 dosya, 14 path ve 23 route tespit edildi — ve prefix'li bir spesifikasyonla tarandığında kuralın öngördüğü tam anlamıyla hatalı pozitif çiftin ortaya çıktığını gördü: aynı route'un bir kez yalnızca-spesifikasyonda, bir kez yalnızca-kodda olarak raporlanması. Öneri, önce spesifikasyon tarafını normalize etmek, ideali uygulamanın kendisinin sunduğu /openapi. ile başlamaktır.

Dev.to gönderisine göre raporlanan testler; ağ veya disk fixture'ı olmadan yaklaşık 0.04 saniyede çalışan 15 saf fonksiyon testini, wheel build, kurulum ve tarama yolunun uçtan uca denetimini ve aracın tam olarak yakaladığı, bir login route'una kasıtlı olarak yerleştirilmiş bir metod uyumsuzluğunu kapsıyor. Bu rakamlar bağımsız bir inceleme değil, yazara aittir.

Belgelenmiş sınırlamalar

README boşlukları açıkça dile getiriyor. Yalnızca OpenAPI 3.x JSON destekleniyor; YAML gelecek çalışmalar arasında listelenmiş. @app.get(f"/users/{id}") gibi f-string ile oluşturulmuş route path'leri çıkarılmıyor; yalnızca string literal'ler çıkarılıyor. Ve karşılaştırma yalnızca route'ları ve HTTP metotlarını kapsıyor — istek ve yanıt şema denetimi sonraki sürümlere bırakılmış.

Neden önemli

Spec-first geliştirme, ancak sözleşmenin her iki tarafını doğrulayan bir şey varsa işler; sıradan bir code review da bir diff'i son commit ile karşılaştırır, aylar önce yazılmış bir spesifikasyonla değil. Spesifikasyon ile uygulama arasındaki sapma, bozuk üretilmiş SDK'ların, yanlış client tiplerinin ve yanıltıcı dokümantasyonun kök nedenidir. Milisaniyeler içinde biten küçük, bağımlılıksız ve salt okunur bir denetleyici, rutin olarak çalıştırılmak için yeterince ucuzdur; çıktısı yapılandırılmış olduğu için takımlar aracın kararını devralmak yerine kendi önem derecesi politikalarını üzerine inşa edebilir. Proje, garanti olmaksızın kişisel bir açık kaynak çalışması olarak GitHub'da yayımlandı; geri bildirim kanalı olarak issue'lar kullanılıyor.