Aynı takımdaki 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=2 ile sayfalandırırken, diğeri ?offset=20 ile sayfalandırır. Biri hataları en üst düzey bir error nesnesine koyarken, diğeri bir message dizesini doğrudan ekler. Her ikisi de kod incelemesini geçer, çünkü inceleyenler isimlendirmeyi değil, mantığı okurlar. Altı ay sonra API yüzeyiniz beş farklı şirket tarafından yazılmış gibi görünür ve her istemci entegrasyonu özel bir durum gerektirir.
Bir OpenAPI linter'ı, bu sapmayı yayınlanmadan önce yakalamak için mevcuttur. OpenAPI belgenizi okur, bir dizi kurala (işlemlerin açıklamalara ihtiyacı vardır, şemaların örneklere ihtiyacı vardır, özellik adları bir büyük/küçük harf kuralına uyar, her yanıt bir medya türü belirtir) karşı çalıştırır ve bir kural çiğnendiğinde derlemeyi başarısız kılar. Bu, JavaScript için ESLint veya Ruby için RuboCop ile aynı fikirdir, ancak uygulama kodunuz yerine API sözleşmenizi hedefler. API tasarım incelemesinin kod biçimlendirmesi gibi otomatikleştirilebilmesini hiç dilediyseniz, bir linter tam olarak bunu yapar.
Bir OpenAPI linter'ı aslında neyi kontrol eder
Bir linter, çalışan bir sunucuda değil, spesifikasyon dosyası üzerinde çalışır. openapi.yaml dosyasına yönlendirin ve her yolu, işlemi, parametreyi, şemayı ve yanıtı tek tek kurallar uygulayarak gezer. Kurallar birkaç kategoriye ayrılır.
Geçerlilik. Bu yasal bir OpenAPI belgesi mi? Her $ref çözülüyor mu? Gerekli anahtar kelimeler mevcut mu? Bu, basit şema doğrulamasıyla örtüşür ve çoğu linter bunu her şeyden önce bir temel olarak yapar.
Eksiksizlik. Her işlem bir operationId, bir özet ve bir açıklamaya sahip mi? Her parametre kendini açıklıyor mu? Her şema bir example taşıyor mu? Bunlar, oluşturulan belgeleri ve SDK'leri gerçekten kullanılabilir kılan kurallardır ve insanlar tarafından en çok unutulanlardır.
Tutarlılık. İşte asıl ödül bu. Özellik adları tek bir büyük/küçük harf kuralı kullanır. Yol segmentleri çoğul isimlerdir. Hata yanıtları tek bir biçimi paylaşır. Her 2xx yanıtı application/json belirtir. Durum kodları, HTTP spesifikasyonunun amaçladığı şekilde kullanılır. Bunların hiçbiri tek başına hata değildir; birlikte, tasarlanmış hissi veren bir API ile bir araya getirilmiş hissi veren bir API arasındaki farkı oluştururlar.
Kurumsal Stil. Kendi kurallarınız. Belki her uç nokta etiketlenmelidir. Belki DELETE 204 döndürmelidir. Belki yalnızca dahili alanlar önek almalıdır. Bunlar kimsenin sahip olmadığı kurallardır ve bunları yazabilme yeteneği, birlikte yaşayabileceğiniz bir linter'ı kavga edeceğiniz birinden ayırır.
Bir kuralın bir ciddiyet seviyesi vardır: hata, uyarı, bilgi veya ipucu. Hatalar derlemeyi başarısız kılar; uyarılar görünür ama geçmesine izin verir. Bu ciddiyet kadranı, mevcut bir API üzerinde linting'i, ilk günden 4.000 ihlalde boğulmadan uygulamanızı sağlar. Her şeye bir uyarı olarak başlayın, en kötülerini düzeltin, sonra ilerledikçe kuralları hataya yükseltin. Bu kuralların neden önemli olduğu ve ekiplerin bunları büyük ölçekte nasıl uyguladığına dair kavramsal taraf için, daha derin arka plan en iyi şirketlerin API tasarım tutarlılığını nasıl sağladığı makalesinde yer almaktadır.
Başlıca OpenAPI linter seçenekleri
Her birinin nereye uyduğunu dürüstçe okuyarak bilmeye değer araçlar burada.
Spectral
Stoplight'tan Spectral, fiili standarttır. OpenAPI 2.0 ve 3.x'i (ve AsyncAPI'yi ve JSONPath aracılığıyla herhangi bir JSON veya YAML'yi) denetleyen açık kaynaklı bir CLI ve kütüphanedir. Sağduyulu kuralları kapsayan yerleşik bir spectral:oas kural seti ile gelir ve asıl gücü özel kurallarıdır: bir YAML dosyasında JSONPath tarzı given seçicileri ve bir then fonksiyonu kullanarak neyi kontrol edeceğinizi açıklarsınız. Geniş bir yerleşik fonksiyon kataloğu (truthy, pattern, casing, length, enumeration) vardır ve bildirimsel formatın ifade edemediği mantığa ihtiyaç duyduğunuzda JavaScript'e geçebilirsiniz.
Güçlü yönleri: her yerde bulunur, en büyük kural ekosistemine sahiptir, VS Code ve diğerleri için düzenleyici eklentileri mevcuttur ve Node'un çalıştığı her yerde çalışır. Tüm sektörün tanıdığı tek bir araç istiyorsanız, bu odur. Dezavantajı, önemsiz olmayan kurallar yazmanın JSONPath'i ve sonunda Spectral'ın fonksiyon API'sini öğrenmek anlamına gelmesidir. Yazarlık konusunda derinlemesine bilgi edinmek isterseniz, TypeScript ile özel Spectral kuralları oluşturma konusunda tam bir rehberimiz var.
Minimal bir .spectral.yaml:
extends: ["spectral:oas"]
rules:
operation-operationId: error
operation-description: warn
property-casing:
description: Properties must be camelCase
given: $.components.schemas..properties[*]~
severity: error
then:
function: casing
functionOptions:
type: camel
Çalıştırmak için:
npx @stoplight/spectral-cli lint openapi.yaml
Redocly CLI
Redocly'nin CLI'si, linting'i paketleme ve belgeleri önizleme ile birleştirir. Linter'ı bir redocly.yaml yapılandırmasını okur, bir dizi yerleşik kural ile gelir ve yapılandırılabilir kural setlerini ve JavaScript ile yazılmış özel eklentileri destekler. Halihazırda Redocly'yi dokümantasyon için kullanan ekipler, ek bir bağımlılık eklemeden aynı araç zincirinde linting elde ederler ve yerleşik kurallar, belgelerin iyi oluşturulmasını sağlayan şeylere yöneliktir.
Güçlü yönleri: belgeler ve paketleme iş akışıyla sıkı entegrasyon, iyi varsayılanlar ve Redocly ekosisteminde yaşıyorsanız tanıdık gelen bir yapılandırma formatı. Henüz orada değilseniz, kural kütüphanesi Spectral'ınkinden daha küçüktür ve özel kural hikayesi daha az geniş çapta belgelenmiştir.
npx @redocly/cli lint openapi.yaml
Vacuum
Vacuum, hız için Go ile yazılmış daha yeni bir linter'dır. Spectral kural setleriyle uyumludur, bu nedenle mevcut bir .spectral.yaml dosyasına işaret edebilir ve büyük spesifikasyonlarda aynı kontrolleri çok daha hızlı çalıştırabilirsiniz. Düzinelerce büyük API belgesine sahip bir monorepo için, çalışma zamanı farkı gerçektir.
Güçlü yönleri: hızlı, Spectral kural seti ile uyumlu, Node çalışma zamanı olmayan tek bir ikili. Spesifikasyonunuz küçükse hız artışı görünmezdir ve ekosistemi ve düzenleyici araçları Spectral'ınkinden daha gençtir, bu nedenle sıfırdan bir seçim olmaktan ziyade bir CI hızlandırıcısı olarak en çekicidir.
Swagger ve openapi-spec-validator
Linter'larla karıştırmamanız için adını anmaya değer. Swagger Editor ve swagger-cli/openapi-spec-validator, bir belgenin geçerli bir OpenAPI olup olmadığını kontrol eder. Bu sadece geçerliliktir, tutarlılık veya kurumsal stil değildir. Her özelliğin farklı adlandırıldığı bir spesifikasyonu seve seve geçireceklerdir, çünkü OpenAPI spesifikasyonunda bunu yasaklayan hiçbir şey yoktur. Doğrulama gereklidir, ancak bu bir tabandır, tavan değil. Swagger ailesi araçları ile tam bir tasarım platformu arasında seçim yapıyorsanız, ödünleşimler API'nizi de test eden Swagger alternatifleri makalesinde açıklanmıştır.
Apidog'daki tasarım anı kontrolleri
Yukarıdaki araçlar bir dosyanız olduktan sonra çalışır. Tutarsızlığı yakalamanın diğer yolu, dosya henüz mevcut değilken, uç noktayı tasarlarken olur. Apidog, tasarım öncelikli bir platformdur: görsel bir düzenleyicide uç noktalar ve veri şemaları oluşturursunuz ve ilerledikçe projenizi dahili olarak tutarlı tutar. Yeniden kullanılabilir veri şemaları, aynı modelin her yerde referans alınması anlamına gelir ve uç nokta başına yeniden tanımlanması yerine, bu da isimlendirme sapmalarının bir sınıfını kökten engeller. Paylaşılan yanıt bileşenleri hata biçimleri için de aynısını yapar.
Apidog, bir Spectral kural setinin doğrudan yerine geçmez; eğer .spectral.yaml kurallarını kullanmaya başladıysanız, onları çalıştırmaya devam edin. Apidog'un değiştirdiği şey, linter'ınızın ilk etapta ne kadar bulduğu sorun miktarıdır. Tasarım yüzeyi yeniden kullanımı zorunlu kıldığında, linter ihlal duvarından ara sıra yakalanan bir duruma geçer. Ve Apidog, standart OpenAPI 3.x'i içe ve dışa aktardığı için, CI'da Spectral veya Vacuum'a verdiğiniz dosya aynı artefakttır, bu nedenle iki katman rekabet etmek yerine üst üste biner.
Bugün çalıştırabileceğiniz bir linter kurulumu
İyi bir kurulum, kontrolü üç farklı yerde, her birinin farklı bir görevi olacak şekilde çalıştırır. Düzenleyici anında geri bildirim sağlar. Ön-commit hook, belirgin hataları yerel olarak durdurur. CI, kimsenin atlayamayacağı kapıdır. İşte her bir katman.
Katman 1: Düzenleyici
Spectral VS Code uzantısını kurun ve repo kökünüze bir .spectral.yaml ekleyin. Uzantı bunu otomatik olarak algılar ve spesifikasyonu düzenlerken ihlallerin altını çizer, tıpkı bir yazım hatasının kırmızı dalgalı çizgi alması gibi. Bu, mümkün olan en ucuz geri bildirim döngüsüdür, çünkü geliştirici sorunu commit olmadan önce düzeltir. Başka yapılandırılacak bir şey yok; repo'daki dosya, kuralların ne olduğuna dair tek doğru kaynaktır.
Katman 2: Ön-commit
Bozuk bir spesifikasyonun uzak depoya ulaşmamasını sağlayacak bir hook ekleyin. Bir package.json betiği artı bir Git hook'u yeterlidir:
{
"scripts": {
"lint:api": "spectral lint openapi.yaml --fail-severity=error"
}
}
# .git/hooks/pre-commit (veya husky aracılığıyla)
#!/bin/sh
npm run lint:api || {
echo "OpenAPI lint başarısız oldu. Commit etmeden önce spesifikasyonu düzeltin."
exit 1
}
--fail-severity=error bayrağı önemli kısımdır. Linter'a sadece hatalarda sıfır olmayan bir değerle çıkmasını söyler, böylece uyarılar commit'i engellemeden yine de yazdırılır. Bu, kuralları hala yükseltirken hook'u kullanılabilir kılar.
Katman 3: CI
Önemli olan kapı budur, çünkü bir takım arkadaşının --no-verify ile atlayamayacağı tek yer burasıdır. Bir GitHub Actions adımı:
name: API lint
on: [pull_request]
jobs:
spectral:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx @stoplight/spectral-cli lint openapi.yaml --fail-severity=error
Spesifikasyon hata düzeyinde bir kuralı bozduğunda iş başarısız olur, çekme isteği kırmızı bir işaret gösterir ve biri onu düzeltene kadar birleştirme engellenir. Tüm uygulama mekanizması budur. Panolar yok, ısrar yok; kural ya yeşildir ya da değildir.
Katman 4: Spesifikasyonun tanımladığı API'yi test edin
Bir linter, spesifikasyonun iyi biçimlendirilmiş ve tutarlı olduğunu kanıtlar. Çalışan API'nin spesifikasyonla eşleşip eşleşmediği hakkında hiçbir şey söylemez. Sözleşme sapmasının saklandığı yer burasıdır: sunucunun üç sürüm önce uygulamayı bıraktığı bir davranışı açıklayan mükemmel bir şekilde denetlenmiş belge. Bu boşluğu kapatmak için, aynı işlem hattında canlı API'ye karşı testler çalıştırırsınız.
İşte burada Apidog CLI linter'ınızın yanına oturur. Bu bir npm paketi, apidog-cli, ve Apidog test senaryolarınızı komut satırından çalıştırır, böylece lint adımından hemen sonra CI'ye yerleşirler:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
apidog run komutu bir test başarısız olduğunda sıfır olmayan bir değerle çıkar, her CI adımının güvendiği aynı sözleşme, böylece başarısız bir test, başarısız bir lint gibi birleştirmeyi engeller. -r junit raporlayıcısı, CI panonuzun bir geçme/kalma ağacına ayrıştırdığı XML'i çıkarır ve -e, aynı senaryoları tekrarlamadan hazırlık veya üretim ortamına yönlendirir. CLI ayrıca bir OpenAPI 3.x belgesini import edebilir, böylece linter'ınızın kontrol ettiği dosya, Apidog'un test ettiği dosya ile aynıdır. Raporlayıcılar ve çıkış kodu yönetimi dahil olmak üzere tam işlem hattı deseni için, CI/CD işlem hattınızda Apidog CLI'yi çalıştırma kılavuzuna bakın. Özellikle GitHub'daysanız, GitHub Actions'taki Apidog CLI kopyala-yapıştır bir iş akışına sahiptir.
Önce lint, sonra test. Lint adımı hızlıdır ve tasarım sorunlarını yakalar; test adımı daha yavaştır ve davranış sorunlarını yakalar. Bunları iki aşama olarak çalıştırın ve bir çekme isteği her ikisini de geçmek zorunda kalır.
Acı çekmeden bir kural setini seçmek ve benimsemek
Aracı seçmek kolay kısımdır. Mevcut bir API üzerinde benimsemek, ekiplerin takıldığı yerdir, çünkü olgun bir spesifikasyondaki ilk çalıştırma yüzlerce ihlal döndürür ve bariz tepki her şeyi kapatmaktır.
Sıfır kuraldan başlamayın ve her kuralı hatadan başlatmayın. Her eklediğinizi uyarı olarak ayarlayarak yerleşik kural setinden (spectral:oas) başlayın. Çalıştırın, sayımı okuyun ve önce geçerlilik hatalarını düzeltin çünkü bunlar gerçek hatalardır. Sonra müşterileriniz için en önemli olan iki veya üç tutarlılık kuralını (genellikle özellik büyük/küçük harf duyarlılığı ve tek bir hata biçimi) seçin ve sadece bunları hataya yükseltin. Diğer her şey uyarı olarak kalır. Her sprint'te, kod tabanı yetişene kadar bir veya iki uyarıyı hataya yükseltin. Bir çeyrek içinde tüm kural seti uygulanmış olur ve kimsenin oraya ulaşmak için yayın yapmayı durdurması gerekmez.
Kurumsal stil kurallarını tutumlu yazın. Her özel kural, birinin sürdürmesi ve sonraki işe alacağı kişiye açıklaması gereken koddur. Bir kural, ancak bir ihlal sizi gerçekten ısırdığında yerini kazanır, olabileceği için değil. Yazdığınız kurallar için, onları nadir hale getirmek üzere tasarım katmanına güvenin: şemalarınız merkezi bir tanımından yeniden kullanılıyorsa, bir özellik büyük/küçük harf duyarlılığı kuralı neredeyse hiç tetiklenmez çünkü adın tanımlandığı tek bir yer vardır. Hangi kuralların uygulanmaya değer olduğu ve hangilerinin boş tartışma olduğu arasındaki kavramsal çerçeve, API tasarım en iyi uygulamaları makalesinde ele alınmıştır.
Eğer ham YAML'den farklı bir dilde tasarım yaparsanız, linter yine de geçerlidir. TypeSpec, OpenAPI'ye derlenir ve yayınlanan belgeyi aynı şekilde denetlersiniz; linter, dosyanın nasıl yazıldığıyla değil, ne söylediğiyle ilgilenir.
Linter'ın büyük tasarım döngüsündeki yeri
Bir linter, tasarım öncelikli bir iş akışında bir kontrol mekanizmasıdır, her şeyin kendisi değildir. Tam döngü şudur: sözleşmeyi tasarla, denetle, müşterilerin ona göre geliştirme yapabilmesi için onu taklit et, uygulamayı ona karşı test et ve ondan belge yayınla. Herhangi bir adımı atlarsanız, diğerleri değerini kaybeder. Kimsenin taklit etmediği denetlenmiş bir spesifikasyon bile ön uç çalışmasını engeller. Kimsenin test etmediği taklit edilmiş bir spesifikasyon bile gerçeklikten sapar.
Bu döngüde tasarımı öncelikli tutmanın nedeni, linting'in çalışmasının nedeni ile aynıdır: sorunları düzeltmenin en ucuz olduğu yerde yakalamak. Tasarım aracında bir özellik adını değiştirmek tek bir düzenlemedir. Üç ekip eski isme karşı yayın yaptıktan sonra değiştirmek bir geçiş işlemidir. Linter, dosya üzerinde tutarlılığı zorlar; tasarım öncelikli bir süreç, dosya var olmadan önce karar üzerinde tutarlılığı zorlar. Sıralama için daha geniş bir argüman isterseniz, API-öncelikli vs API tasarım-öncelikli vs kod-öncelikli ödünleşimleri ortaya koyar ve sözleşme-öncelikli API tasarım araçları bunu destekleyen araçları kapsar.
Apidog, tüm bu döngüyü tek bir yerde kapsar: yeniden kullanılabilir şemalarla tasarım yapın, anında taklit edin, CI'da CLI ile test edin ve hangi linter'ı standartlaştırırsanız standartlaştırın, temiz OpenAPI'yi dışa aktarın. Linter'ın hala bir işi var; yakalaması gereken sadece daha az şey var.