Spectral ile OpenAPI Lintleme: Daha Kolay Bir Yöntem

Aynı ekipteki iki mühendis aynı hafta içinde iki uç nokta yayınlar. Biri created_at döndürürken, diğeri createdAt döndürür. Biri ?page= ile sayfalandırırken, diğeri ?offset= ile sayfalandırır. Tek başına hiçbiri yanlış değildir. Ancak birlikte, API'nizin yabancılar tarafından bir araya getirilmiş gibi hissettirmesine neden olurlar ve onu tüketen her istemci bunun bedelini öder. OpenAPI dosyası sorunsuz doğrulanır. Ayrıştırılır, Swagger UI'da görüntülenir, bir SDK oluşturur. Sadece tutarsızdır ve basit bir doğrulayıcının bu konuda söyleyecek hiçbir şeyi yoktur.

İşte bir kod denetleyicisinin (linter) doldurduğu boşluk tam da budur. Bir doğrulayıcı "bu spesifikasyon yasal bir OpenAPI mi?" sorusunu yanıtlarken, bir kod denetleyicisi "bu spesifikasyon üzerinde anlaştığımız kurallara uyuyor mu?" sorusunu yanıtlar. İkinci soru için en popüler açık kaynaklı araç, JSON ve YAML belgeleri için Stoplight'ın kod denetleyicisi olan Spectral'dır. Dahili bir OpenAPI kurallar seti ile birlikte gelir, kendi kurallarınızı yazmanıza olanak tanır ve terminalden veya düzenleyicinizden çalışır. Bir API stil kılavuzunu uygulamak için ücretsiz, betiklenebilir bir yol arıyorsanız, Spectral bariz ilk duraktır ve bu kılavuz size onu nasıl doğru kullanacağınızı gösterir.

Ayrıca size değiş tokuşu da gösterir. Spectral, sizin derleyip sürdürdüğünüz bir kurallar setidir. YAML kurallarını elle yazmadan tutarlılık kontrollerini, sahte sunucuları ve çalıştırılabilir testleri tek bir yerden almak isteyen ekipler için Apidog bu işi doğrudan tasarım yüzeyine entegre eder. Önce Spectral'ı tam olarak takdir edecek, ardından hepsi bir arada yaklaşımın size bakım masrafından nasıl tasarruf ettirdiğini göstereceğiz.

Spectral aslında ne yapar?

Spectral genel bir kod denetleyicisidir. Onu yapılandırılmış bir belgeye yöneltir, bir dizi kural verirsiniz ve belge içinde bir kuralı bozan her yeri, satır numarası ve şiddetiyle birlikte rapor eder. OpenAPI'ye özel değildir; OpenAPI, AsyncAPI ve Arazzo'yu kutudan çıktığı gibi anlar ve herhangi bir JSON veya YAML dosyasını özel kurallarla denetleyebilirsiniz.

API çalışmaları için önemli olmasının nedeni, yerleşik spectral:oas kural setidir. Bu kural seti, uzun bir OpenAPI kural listesini içerir: işlemlerin bir operationId'ye sahip olması, info nesnesinin bir açıklama ve iletişim bilgisi taşıması, etiketlerin kullanılmadan önce tanımlanması, parametrelerin birbirini tekrar etmemesi gerekir. Bunu gerçek dünya bir spesifikasyon üzerinde çalıştırdığınızda, neredeyse her zaman ilk denemede bir uyarı listesi alırsınız. Hiçbiri bir ayrıştırıcıyı bozmaz. Ancak hepsi spesifikasyonla yaşanmasını zorlaştırır.

Bu, yapısal doğrulamadan farklı bir iştir. swagger-cli veya Redocly gibi bir araç, belgenin OpenAPI şemasına uygun olup olmadığını yanıtlar. Spectral ise belgenin bunun yanı sıra sizin kurum içi stilinizi takip edip etmediğini yanıtlar. İkisini de istersiniz ve bu iki kontrol bir işlem hattında sorunsuz bir şekilde birleşir. Doğrulama kısmını OpenAPI spesifikasyonları nasıl doğrulanır kılavuzunda ele alıyoruz; bu makale stil ve tutarlılık kısmıyla ilgilidir.

Spectral'ı kurma ve ilk denetiminizi çalıştırma

Spectral bir npm paketi olarak gelir. CLI, `@stoplight/spectral-cli`'dır. Genel olarak kurun:

npm install -g @stoplight/spectral-cli

Node.js tek sistem bağımlılığıdır, bu nedenle Node'un zaten yüklü olduğu herhangi bir makine veya CI imajı onu çalıştırabilir. Genel olarak kurmak istemiyorsanız, npx @stoplight/spectral-cli ... geçici derleme çalıştırıcılarında işe yarar.

Spectral neyi kontrol edeceğini bilmek için bir kural setine ihtiyaç duyar. Kural olarak çalışma dizininizde .spectral.yaml adında bir dosya bulunur. En küçük kullanışlı olanı, yerleşik OpenAPI kurallarını genişletir:

# .spectral.yaml
extends: ["spectral:oas"]

Şimdi bir spesifikasyonu denetleyin. Mevcut dizinde bir .spectral.yaml dosyası varsa, Spectral bunu otomatik olarak algılar:

spectral lint openapi.yaml

Veya açıkça bir kural setine işaret edin:

spectral lint openapi.yaml --ruleset .spectral.yaml

Çıktı bilerek okunabilir olacak şekilde tasarlanmıştır. Her bulgu satırı ve sütunu, şiddeti, tetiklenen kuralı ve okunabilir bir mesajı gösterir:

openapi.yaml
  3:6   uyarı  info-contact      Bilgi nesnesi `contact` nesnesini içermelidir.
  5:10  hata    info-description   OpenAPI nesne bilgisi `description` mevcut olmalıdır.

✖ 2 sorun (1 hata, 1 uyarı, 0 bilgi, 0 ipucu)

Mevcut bir spesifikasyona karşı yapılan ilk çalıştırma, çoğu ekibin ne kadar kayma yaşandığını fark ettiği andır. Kurallar hiçbir zaman uygulanmadı, bu yüzden kimse onları takip etmedi.

Kendi kurallarınızı yazma

Yerleşik kural seti bir başlangıç noktasıdır, varış noktası değil. Spectral'ın gerçek değeri, ekibinizin kurallarını bir makinenin her değişiklikte kontrol ettiği kurallar olarak kodlamaktır. Bir kuralın dört hareketli parçası vardır: neye bakılacağı (given, bir JSONPath ifadesi), neyin kontrol edileceği (then, bir fonksiyon), ne kadar yüksek sesle uyarı verileceği (severity) ve başarısız olduğunda ne söyleneceği (message).

İşte yaygın bir şirket içi kural olan kebab-case yollarını zorunlu kılan bir kural:

# .spectral.yaml
extends: ["spectral:oas"]
rules:
  paths-kebab-case:
    description: Yollar kebab-case olmalıdır.
    message: "{{property}} kebab-case olmalıdır (küçük harf, tire ile ayrılmış)"
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(\\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"

given her yol anahtarını seçer. then ise yerleşik pattern fonksiyonunu bir düzenli ifadeye karşı çalıştırır. Desene uymayan her şey, mesajınızla birlikte bir uyarı olarak rapor edilir. Tamsayı ID'lerini UUID'ler lehine yasaklayabilir, her POST işleminde bir hata yanıtı isteyebilir, sunucu URL'lerinde sürüm numaralarını yasaklayabilir veya her işlemin bir açıklama taşımasını zorunlu kılabilirsiniz. Spectral, birkaç temel fonksiyon (truthy, pattern, schema, length, enumeration ve daha fazlası) ile birlikte gelir, bu nedenle çoğu kural için hiç kod gerekmez.

Bir kuralın, bir fonksiyon seçeneğinin ifade edemeyeceği bir mantığa ihtiyacı olduğunda, Spectral size JavaScript veya TypeScript'te kurallar yazma ve özel fonksiyonlar içe aktarma olanağı tanır. Aracın güçlü hale geldiği ve bakımın başladığı yer burasıdır. Bu kadar derine inmek isterseniz, TypeScript ile özel Spectral kuralları oluşturma üzerine kapsamlı bir kılavuzumuz var.

Şiddet ve derlemenin başarısız olmasını sağlama

Her Spectral kuralının bir şiddeti vardır: error (hata), warn (uyarı), info (bilgi) veya hint (ipucu). Varsayılan olarak CLI, yalnızca bir error bulduğunda sıfırdan farklı bir kodla çıkar. Uyarılar yazdırılır ancak çalıştırmayı başarısız kılmaz. Bu, eski bir spesifikasyonu temizlerken ve her birleştirmeyi binlerce uyarının engellemesini istemediğinizde sorun değildir.

Spesifikasyonunuz temizlendiğinde, kapıyı sıkılaştırın. --fail-severity bayrağı eşiği kontrol eder:

spectral lint openapi.yaml --fail-severity=warn

Artık bir uyarı da çıkış kodu 1 döndürür, bu da bir CI adımının kendisini başarısız olarak işaretlemesi için okuduğu şeydir. Bu, bir kod denetleyicisini gerçek bir kalite geçidine dönüştüren mekanizmadır: spesifikasyon stil kılavuzundan saptığı anda işlem hattı birleştirmeyi engeller. Kural setinizde tek tek kural şiddetlerini de geçersiz kılabilir, önemsediğiniz bir kuralı warn'dan error'a yükseltebilir veya ekibinize uymayan birini off olarak ayarlayarak susturabilirsiniz.

Spectral'ı CI'da çalıştırma

Birinin hatırladığı zamanlarda çalışan bir kod denetleyicisi bir geçit değildir. Amaç, her itmede, temiz bir makinede, herkes için aynı kural setiyle çalıştırmaktır. Spectral bunu kısa ve öz hale getirir. İşte dokunduğu herhangi bir çekme isteğinde spesifikasyonu denetleyen bir GitHub Actions işi:

name: Lint OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g @stoplight/spectral-cli
      - run: spectral lint openapi.yaml --fail-severity=warn

Daha zengin raporlama için Spectral, çoğu CI panosunun bir geçme/kalma ağacına ayrıştırdığı JUnit XML'i üretebilir:

spectral lint openapi.yaml -f junit -o results.xml

Bu yapıtı panonuza bağlayın ve her katkıda bulunan, ham günlükleri okumadan hangi kuralın nerede başarısız olduğunu görür. Yapısal kontrolleri, kod denetimini ve kırıcı değişiklik algılamayı bir araya getiren daha geniş resmi istiyorsanız, CI'daki OpenAPI desenleri tek bir aracın ötesine genellenir. Spesifikasyonu kod olarak ele almak tüm bunları kalıcı kılan zihniyettir.

Spectral'ın sizden çok şey istediği yerler

Spectral yaptığı işte iyidir. Dürüst olursak, sadece tek bir şey yapar ve spesifikasyon yaşam döngüsünün geri kalanını bir araya getirmek sizin sorununuzdur. Bir ekip demoyu geçip onu benimsediğinde birkaç gerçek ortaya çıkar.

Kural setinin sahibi sizsiniz. Yerleşik spectral:oas kuralları geneldir. Gerçek stil kılavuzunuz, sizin yazdığınız, gözden geçirdiğiniz, sürümlendirdiğiniz ve kurallar geliştikçe güncel tuttuğunuz özel kurallarda yaşar. Bu kural seti, kendi bakım yükü olan küçük bir kod tabanına dönüşür ve JSONPath artı özel fonksiyonlar, ekipteki herkesin sahip olduğu bir beceri değildir.

Belgeyi denetler, API'yi değil. Spectral dosyayı okur. Çalışan servisin spesifikasyonun vaat ettiği şeyi gerçekten döndürüp döndürmediğini size söyleyemez. Bir spesifikasyon her denetim kuralını geçebilir ve yine de uygulamanın aylarca önce saptığı bir uç noktayı tanımlayabilir. Bu boşluğu kapatmak, gerçek istekler göndermek ve yanıtları doğrulamak anlamına gelir ki bu tamamen farklı bir araçtır.

Daha uzun bir zincirin bir parçasıdır. Kod denetiminden sonra bile ön uç ekipleri için sahte veriler, bir dokümantasyon sitesi ve otomatik bir test paketi hala ihtiyacınız olacaktır. Her biri, spesifikasyonla uyumlu tutulması, kurulması ve yapılandırılması gereken ayrı bir araçtır. Kod denetleyicisi bunların hiçbirini bilmez, bu nedenle spesifikasyon her aşamada yeniden ayrıştırılır ve yeniden yorumlanır.

Bunların hiçbiri Spectral'a bir eleştiri değildir. Odaklanmış bir kod denetleyicisidir ve kapsamı konusunda dürüsttür. Ancak "odaklanmış" demek, entegrasyon işinin size kaldığı anlamına gelir.

Daha kolay yol: tutarlılığın tasarım yüzeyine entegre edilmesi

İşte diğer yol. Tutarlılığı, spesifikasyon yazıldıktan sonra eklenen bir denetim adımı olarak ele almak yerine, Apidog bunu spesifikasyon yazmanın bir parçası olarak görür.

Apidog hepsi bir arada bir API platformudur: şemayı tasarlar, isteklerin hatalarını ayıklar, test senaryoları oluşturur, uç noktaları taklit eder ve belgeleri tek bir çalışma alanında yayınlarsınız. Tasarım aracın içinde gerçekleştiği için, tutarlılık kontrolleri siz yazarken yapılır. Görsel tasarımcı, yapısal sorunları ortaya çıktıkları anda, bir derleyicinin sözdizimi hatasını altını çizdiği gibi yüzeye çıkarır, böylece taahhüde ulaşmadan önce onları düzeltirsiniz. Sonradan ayrı bir kod denetleyicisi çalıştırmazsınız; düzenleyici kod denetleyicisidir.

Daha büyük fark ise aşağı yöndeki her şeydir. Tasarladığınız aynı sözleşme, yeniden ayrıştırmaya veya senkronize tutulacak ikinci bir araca gerek kalmadan sahte sunucunuz, etkileşimli dokümanlarınız ve test senaryolarınız olur. Bu kontrolleri bir işlem hattında istediğinizde, Apidog CLI test senaryolarınızı terminalden başsız olarak çalıştırır ve başarısızlık durumunda sıfırdan farklı bir çıkış koduyla çıkar; tıpkı bir kod denetleyicisinden istediğiniz geçit davranışı gibi, ancak sadece dosyayı okumak yerine çalışan API'yi sözleşmeye karşı test eder. Tek bir npm komutuyla kurun ve bir senaryoya yönlendirin:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -r cli

Bu, Spectral'ın açık bıraktığı boşluğu doldurur. Spectral, belgenin stilinize uyduğunu doğrular. Apidog CLI, uygulamanın hala belgeyle eşleştiğini doğrular. Tam bayrak referansı için apidog run --help komutunu çalıştırın veya tam CLI kılavuzunu okuyun.

Öyleyse değiş tokuş gerçektir ve açıkça belirtilmeye değerdir. Spectral size monte edip sürdürdüğünüz ücretsiz, betiklenebilir, satıcıdan bağımsız bir kod denetleyicisi sunar. Apidog ise size tutarlılık, sahte sunucular, belgeler ve çalıştırılabilir testleri tek bir doğru kaynaktan, çok daha az bağlantı kurma ihtiyacıyla verir. Mevcut bir araç zincirinde taşınabilir bir denetim adımı ihtiyacınız olan tek şeyse, Spectral iyi bir cevaptır. Tüm yaşam döngüsünün kendi başına bir araç projesi haline gelmeden sürdürülmesini istiyorsanız, entegre yol zamanla size daha az maliyetli olacaktır.

Spectral ve Apidog'a bir bakış

Tabloyu bir karar yardımcısı olarak kullanın, bir skor tahtası olarak değil. Doğru seçim, yaşam döngüsünün ne kadarını tek bir aracın yönetmesini istediğinize uygun olandır.

Sıkça sorulan sorular

Spectral ücretsiz mi? Evet. Spectral, Stoplight tarafından sürdürülen Apache 2.0 lisansı altında açık kaynaktır. CLI, yerleşik OpenAPI kural seti ve özel kural yazma özelliklerinin hepsi ücretsizdir.

Spectral, spesifikasyonumun yasal OpenAPI olduğunu doğruluyor mu? Kısmen. Yerleşik kurallar birçok yapısal sorunu yakalar, ancak Spectral bir kod denetleyicisi (linter) olup, özel bir şema doğrulayıcı değildir. Tam yapısal kapsama için bir doğrulayıcı ile birlikte kullanın. OpenAPI spesifikasyonlarını doğrulama kılavuzu bu tarafı ele alır ve en iyi OpenAPI doğrulayıcı araçları seçenekleri karşılaştırır.

Spectral çalışan API'mi test edebilir mi? Hayır. Spectral sadece spesifikasyon dosyasını okur. Canlı API'nin sözleşmeyle eşleştiğini kontrol etmek için, gerçek istekler gönderen ve yanıtları doğrulayan bir çalıştırıcıya ihtiyacınız vardır; örneğin Apidog CLI.

Bir Spectral uyarısının CI derlememi başarısız kılmasını nasıl sağlarım? `spectral lint openapi.yaml --fail-severity=warn` komutunu çalıştırın. Varsayılan olarak yalnızca `error` şiddeti derlemeyi başarısız kılar; `--fail-severity=warn` uyarıların da sıfırdan farklı bir çıkış kodu döndürmesini sağlar.

Spectral ve Apidog arasındaki fark nedir? Spectral, yapılandırdığınız ve sürdürdüğünüz odaklanmış bir açık kaynak kod denetleyicisidir. Apidog ise tasarımın, tutarlılık kontrollerinin, sahte sunucuların, belgelerin ve testlerin bir arada bulunduğu hepsi bir arada bir platformdur, böylece daha az şey birleştirir ve daha az şeyi senkronize tutarsınız. Tasarım aracı ortamının ilgili bir karşılaştırması için Apidog ve Swagger makalesine bakın.

Sonuç

Spectral, basit doğrulayıcıların göz ardı ettiği gerçek bir sorunu çözer: bir OpenAPI spesifikasyonunu ekibinizin üzerinde anlaştığı kurallara uygun tutmak. `@stoplight/spectral-cli`'ı kurun, `spectral:oas`'ı genişletin, birkaç özel kural ekleyin ve işlem hattınızı `--fail-severity=warn` ile koruyun. Birçok ekip için bu yeterlidir ve hiçbir maliyeti yoktur.

Maliyet daha sonra, sürdürdüğünüz kurallarda ve kod denetleyicisinin etrafında birleştirdiğiniz yaşam döngüsünün geri kalanında ortaya çıkar. Tutarlılık, sahte sunucular, belgeler ve çalıştırılabilir testleri tek bir doğru kaynaktan almak isterseniz, Apidog'u indirin ve kontrollerin zaten yüzeyin bir parçası olduğu yerlerde spesifikasyonunuzu oluşturun. Her iki durumda da hedef aynıdır: tüm ekibinizin güvenebileceği, bir umut yerine bir makine tarafından uygulanan bir spesifikasyon.