Tobias Hoffmann

Posted on Jul 14 • Originally published at apidog.com

Stoplight'tan Apidog'a Geçiş Rehberi: Spec-First Modunda OpenAPI Spesifikasyon Yönetimi

Stoplight'tan Apidog'a geçiş, yalnızca bir OpenAPI dosyasını içe aktarmak değildir. Dosya tabanlı API sözleşmesini, belgeleri, şemaları, navigasyonu ve ekip iş akışlarını birlikte taşıyıp doğrulamanız gerekir.

Apidog'u bugün deneyin

Birçok Stoplight projesi, uç nokta tanımlarından daha fazlasını içerir:

Git'te tutulan OpenAPI spesifikasyonları
Markdown belgeleri
JSON Schema model dosyaları
Yerel görseller
toc.json tabanlı navigasyon
.stoplight.json yol ayarları
x-stoplight-id veya x-stoplight.id gibi Stoplight kimlikleri

Ekipte ayrıca Postman istek örnekleri, Bruno .bru dosyaları veya CI test betikleri bulunabilir. Yalnızca OpenAPI dosyasını içe aktarırsanız uç noktalar taşınabilir; ancak belgeler, navigasyon, testler ve günlük çalışma düzeni kopabilir.

Apidog Spec-first Modu, OpenAPI dosyalarını doğruluk kaynağı olarak tutarken bu dosyaları belgeler, mock API'ler, testler, raporlar, izinler ve ekip iş birliğiyle bağlamanıza yardımcı olur.

Bu rehberde şunları ele alacağız:

Hangi Stoplight varlıklarının aktarılabileceği
Hangi yapıların inceleme gerektirdiği
Hangi iş akışlarının yeniden oluşturulması gerektiği
API sözleşmesinin Apidog iş akışına nasıl bağlanacağı

Operasyonel kurulum ayrıntıları için Spec-first Modu yardım rehberine bakın.

Neden Stoplight Geçişi Bir OpenAPI İçe Aktarımından Daha Fazlasıdır?

Bir OpenAPI dosyası API sözleşmesini tanımlar. Ancak Stoplight tarzı bir proje, bu sözleşme etrafındaki ek bağlamı da içerir.

Yaygın proje varlıkları şunlardır:

OpenAPI veya Swagger dosyaları; genellikle reference gibi dizinlerde bulunur
Markdown belgeleri; çoğunlukla docs altında tutulur
JSON Schema model dosyaları; genellikle models altında bulunur
Belgelerden referans verilen yerel görseller
Yol yapılandırması için .stoplight.json
Belge gruplama ve sıralaması için toc.json
x-stoplight-id veya x-stoplight.id gibi Stoplight kimlikleri

Tek bir OpenAPI dosyasını içe aktarmak, yalnızca uç nokta listesini taşır. Aşağıdaki parçalar ayrı olarak ele alınmazsa kaybolabilir veya bozulabilir:

Markdown sayfaları ve göreceli bağlantılar
TOC sıralaması ve belge grupları
JSON Schema referansları
Görsel dosya yolları
Test senaryoları
Mock API yapılandırmaları
Postman veya Bruno istek akışları
CI doğrulama ve raporlama işleri

Bu nedenle geçiş planına tek bir spesifikasyon dosyasından değil, depo ağacından başlayın.

Geçiş Modeli: Aktar, İncele, Yeniden Oluştur, Bağla

Başlamadan önce gerçek doğruluk kaynağını belirleyin.

Git'teki OpenAPI dosyaları API sözleşmesini tanımlıyorsa, Spec-first geçişine bu dosyalardan başlayın. Postman veya Bruno koleksiyonları gerçek davranışı belirliyorsa, önce OpenAPI ile koleksiyonlar arasındaki farkı çözün.

En iyi yaklaşım “her şeyi bire bir korumaya çalışmak” değildir. Stoplight projelerinde, başka bir çalışma alanına doğrudan karşılık gelmeyen ürüne özgü davranışlar olabilir.

Bunun yerine dört aşamalı bir model kullanın:

Kategori	Buraya ne ait?	Geçiş yaklaşımı
Aktar	OpenAPI dosyaları, desteklenen `.stoplight.json` yol ayarları, desteklenen `toc.json` girdileri, Markdown belgeleri, referanslı yerel görseller ve uygun JSON Schema modelleri	Dosya tabanlı proje bağlamını Spec-first Moduna taşıyın.
İncele	Markdown bağlantıları, anchor noktaları, görseller, TOC grupları, şema adları, harici `$ref` kullanımları, Stoplight kimlikleri ve işleme farkları	Geçirilen çalışma alanını üretim kullanımı öncesinde doğrulayın.
Yeniden Oluştur	Postman/Bruno akışları, ortamlar, manuel testler, mock'lar, CI işleri ve yayınlama kuralları	Bunları OpenAPI doğruluk kaynağı çevresinde yeniden bağlayın.
Bağla	Belgeler, mock API'ler, testler, CI raporları, izinler, ekip iş birliği ve partner iş akışları	API yaşam döngüsünü sözleşmeye bağlamak için Apidog'u kullanın.

Bu ayrım önemlidir çünkü Stoplight geçişinin iki katmanı vardır.

Dosya katmanı şunları kapsar:

OpenAPI spesifikasyonları
Markdown belgeleri
Model dosyaları
Görseller
Proje yapılandırma dosyaları

Spec-first Modu en doğrudan bu katmanda fayda sağlar.

İş akışı katmanı ise ekibin şu süreçlerini kapsar:

API değişikliklerini inceleme
Belgeleri yayınlama
Testleri çalıştırma
Mock API'leri yönetme
Raporları paylaşma
Backend, frontend, QA, ürün ve partner ekipleriyle iş birliği yapma

Bu katmanı içe aktarımın otomatik bir sonucu olarak görmeyin. Geçiş sonrası bilinçli olarak yeniden oluşturun.

Apidog Spec-first Modu Stoplight Projelerine Nasıl Uyar?

Apidog Spec-first Modu, dosya tabanlı API iş akışları için tasarlanmıştır.

Git bağlantılı projelerde depo merkezde kalır. Dalınız doğruluk kaynağı olmaya devam eder ve Apidog değişikliklerle senkronize olur.

Dosya destekli projelerde ise önce Apidog içinde spesifikasyon dosyalarıyla çalışabilir, Git bağlantısını daha sonra kurabilirsiniz.

Spesifikasyonlar çalışma alanı şunları tek noktada yönetmenizi sağlar:

Kaynak OpenAPI dosyaları
Ayrıştırılmış API yapısı
Uç noktalar ve şemalar
Dosya düzenleme akışları
Doğrulama sonuçları

Spesifikasyonlar çalışma alanı, ekiplerin kaynak dosyalarını, ayrıştırılmış API yapısını ve düzenleme iş akışlarını tek bir yerden yönetmelerini sağlar.

Stoplight Varlıkları Apidog'da Nasıl Ele Alınır?

Stoplight varlığı	Apidog'da ne olur?	İnceleme notları
OpenAPI / Swagger dosyaları	API modülleri, uç noktalar, şemalar ve örnekler olarak içe aktarılabilir ve senkronize edilebilir.	Paketlenmiş referansları, dönüştürme uyarılarını, modül adlarını ve uç nokta gruplarını kontrol edin.
`.stoplight.json`	Desteklenen alanlar; OpenAPI, Markdown ve JSON Schema köklerini bulmaya, OpenAPI dahil etme/hariç tutma desenlerini uygulamaya ve `tocPath` çözümlemeye yardımcı olabilir.	Bunu tam proje yapılandırması değil, senkronizasyon için yol keşfi olarak değerlendirin.
`toc.json`	DOCS klasörleri, Markdown sıralaması, TOC başlıkları, OAS/modül bağlantıları ve desteklenen model içe aktarımları için kullanılabilir.	Son kenar çubuğunu mutlaka inceleyin. Tam Stoplight navigasyonu korunmayabilir.
Markdown belgeleri	Proje iş akışına aktarılabilir. TOC'de listelenen belgeler daha fazla yapı koruyabilir.	Dahili bağlantıları, anchor noktalarını, eksik dosyaları ve işleme farklarını kontrol edin.
Yerel görseller	Markdown tarafından referans veriliyorsa desteklenen durumlarda aktarılabilir.	Bozuk bağlantıları, harici görselleri, veri URI'larını ve kullanılmayan dosyaları kontrol edin.
JSON Schema modelleri	`toc.json` gibi desteklenen yapı tarafından açıkça referans veriliyorsa Modellere aktarılabilir.	Şema formatını, isimleri, klasörleri ve `$ref` ilişkilerini doğrulayın.
Stoplight kimlikleri	Kök seviyedeki kimlikler, tekrar senkronizasyonlarda modül eşleştirmesine yardımcı olabilir.	Uç nokta veya sayfa seviyesindeki tüm kimliklerin korunacağını varsaymayın.

Stoplight Proje Dosyaları İçin Uyumluluk Notları

.stoplight.json, desteklenen yol yapılandırma alt kümesi olarak ele alınmalıdır. Apidog; OpenAPI, Markdown ve JSON Schema köklerini, OpenAPI dahil etme desenlerini, genel hariç tutma desenlerini ve tocPath değerini kullanabilir.
toc.json, DOCS klasörleri, Markdown sıralaması, OAS/modül bağlantıları, seçili spesifikasyon öğesi bağlantıları ve TOC referanslı model içe aktarımları için yardımcı olabilir.
Son belge kenar çubuğu Apidog'un DOCS/OAS/MODELLER modeline göre üretildiği için, rastgele Stoplight düzenleri veya tam çapraz tür sıralaması korunmayabilir.
Görseller öncelikle Markdown tarafından referans verildiğinde taşınır. Referans verilmeyen varlıkları ayrıca inceleyin.
JSON Schema dosyaları, yalnızca bir dizinde bulundukları için değil, toc.json gibi desteklenen yapı tarafından açıkça referans verildiklerinde daha öngörülebilir şekilde içe aktarılır.

Amaç Stoplight'ı piksel piksel yeniden oluşturmak değildir. Amaç, taşınabilir dosya tabanlı proje bağlamını korumak ve bunu daha geniş bir API yaşam döngüsüne bağlamaktır.

Dosya İçe Aktarımından Bağlı API İş Akışına

Geleneksel içe aktarma akışında ekipler bir OpenAPI dosyasını bir kez içe aktarır ve ardından yeni araçta görsel olarak çalışır. Bu yaklaşım zamanla kaymaya yol açabilir:

Git'teki dosya güncel değildir.
Belge sitesi farklı bir sözleşmeyi gösterir.
API çalışma alanı başka bir sürümü temsil eder.
Testler ve mock'lar eski örnekleri kullanır.

Spec-first Modunda dosyalar temel olmaya devam eder.

Git bağlantılı bir Spec-first projesinde şu akışı uygulayabilirsiniz:

Depoyu ve hedef dalı bağlayın.
Spesifikasyonlar çalışma alanında dosyaları inceleyin veya düzenleyin.
Değişiklikleri doğrulayın.
Değişiklikleri taahhüt edin.
Güncellenmiş dosyaları depoya geri gönderin.

Dosya destekli projede ise Git bağlamadan önce Apidog'da dosyaları düzenleyip kaydedebilirsiniz.

Sorumluluk	Önerilen kaynak
API sözleşmesi	OpenAPI / Swagger dosyaları
Proje dosya yapısı	Depo veya dosya destekli proje ağacı
Stoplight tarzı desteklenen yol ayarları	`.stoplight.json`
Desteklenen belge navigasyonu	`toc.json` ve Markdown belgeleri
Günlük API iş birliği	Apidog proje çalışma alanı
Mock'lar, testler, raporlar ve izinler	Apidog platform iş akışı

Bu yaklaşımın temel değeri şudur: Dosya öncelikli sözleşme modelini korurken, sözleşmeyi daha fazla paydaş için kullanılabilir hale getirirsiniz.

Git Bağlantılı ve Dosya Destekli Geçiş Yolları

Stoplight ekipleri aynı iş akışı olgunluk seviyesinde değildir.

Bazı ekipler API değişikliklerini Git dalları ve pull request'ler üzerinden yönetir. Bazıları ise API spesifikasyonlarını dosya olarak tutar ancak ilk geçiş aşamasında Git sağlayıcısını bağlamak istemez.

Apidog Spec-first Modu iki yaklaşımı da destekler.

Yol	En uygun kullanım	Tipik iş akışı
Git bağlantılı Spec-first projesi	OpenAPI spesifikasyonlarını Git'te yöneten ekipler	Depoyu bağlayın, dalı senkronize edin, dosyaları düzenleyin, commit edin ve push edin.
Dosya destekli Spec-first projesi	Git bağlantısından önce dosya tabanlı tasarım yapmak isteyen ekipler	Apidog'da spesifikasyon dosyalarıyla çalışın, değişiklikleri kaydedin ve iş akışını doğrulayın.

Çoğu Stoplight geçişinde Git bağlantılı proje daha net bir uzun vadeli model sunar. Depo, sözleşmenin doğruluk kaynağı olmaya devam eder.

Dosya destekli yaklaşım ise şu durumlarda faydalıdır:

Yazma deneyimini değerlendirmek istiyorsanız
Proje dosyalarını önce temizlemek istiyorsanız
Git tabanlı sürece aşamalı geçmek istiyorsanız
Küçük bir pilot geçiş yapmak istiyorsanız

Geçiş Sonrası Neler İncelenmeli?

Dosyalar başarıyla aktarılmış görünse bile bir inceleme turu yapın. Bu özellikle büyük dokümantasyon siteleri, çok sayıda şema dosyası veya özelleştirilmiş Stoplight navigasyonu kullanan ekipler için önemlidir.

Spec-first projesini oluşturduktan sonra aşağıdaki kontrol listesini uygulayın.

Alan	Kontrol edilmesi gerekenler
OpenAPI modülleri	Hedeflenen tüm spesifikasyon dosyalarının içe aktarıldığını, modül adlarının doğru olduğunu ve uç noktaların beklendiği gibi gruplandığını doğrulayın.
Harici referanslar	`$ref` bağımlılıklarının çözümlendiğini ve dönüştürme uyarıları olup olmadığını kontrol edin.
Lint / doğrulama	İçe aktarılan OpenAPI dosyalarında Apidog Spesifikasyonlar doğrulamasını çalıştırın.
`.stoplight.json`	Desteklenen OpenAPI, Markdown ve JSON Schema köklerini; dahil etme/hariç tutma desenlerini ve `tocPath` değerini doğrulayın.
`toc.json`	Grupları, ayırıcıları, başlıkları, Markdown sıralamasını, OAS/modül bağlantılarını ve nihai kenar çubuğunu inceleyin.
Markdown belgeleri	Başlıkları, biçimlendirmeyi, göreceli bağlantıları, anchor noktalarını ve API işlem bağlantılarını kontrol edin.
Görseller	Yerel referanslı görsellerin işlendiğini; harici görseller, veri URI'ları ve bozuk bağlantıların ayrıca ele alındığını doğrulayın.
Modeller	TOC referanslı JSON Schema dosyalarının doğru model kaynağına dönüştüğünü; isim, klasör ve referansların doğru olduğunu kontrol edin.
Stoplight kimlikleri	Tekrarlanan senkronizasyonlarda modül eşleştirmesini doğrulayın.
Testler ve mock'lar	Postman, Bruno, CI veya başka araçlarda tutulan senaryoları yeniden oluşturun ya da bağlayın.
İzinler ve yayınlama	Ekip erişimi, belge görünürlüğü, inceleme kuralları ve yayınlama sorumluluklarını yeniden yapılandırın.

Apidog, Spectral tabanlı editör doğrulaması için kök seviyedeki şu dosyaları kullanabilir:

.spectral.yaml
.spectral.yml
.spectral.json
.spectral.mjs

Gerekirse .stoplight/styleguide.json dosyasına geri dönebilir.

Doğrulama bulgularını inceleme sinyali olarak kullanın. Lint kontrolünün başarılı olması, Stoplight'a özgü tüm davranışların korunduğu anlamına gelmez.

Postman ve Bruno Varlıkları Hakkında Ne Yapılmalı?

Birçok Stoplight ekibi Postman veya Bruno da kullanır. Bu varlıkları OpenAPI geçişinden ayrı planlayın.

OpenAPI dosyaları API sözleşmesini tanımlar. Postman koleksiyonları ve Bruno .bru dosyaları ise çoğunlukla şunları tanımlar:

İstek akışları
Örnek istekler
Ortam değişkenleri
Sırlar
Testler
Koleksiyon düzeyinde betikler

Geçiş öncesinde şu soruları yanıtlayın:

Soru	Neden önemli?
OpenAPI mi doğruluk kaynağı, yoksa koleksiyonlar mı gerçek API davranışını yönlendiriyor?	Spec-first geçişi yetkili sözleşmeden başlamalıdır.
Hangi istek örnekleri hâlâ önemli?	Kritik örnekleri bağlı API çalışma alanında yeniden oluşturun.
Hangi testler çalışmaya devam etmeli?	Testleri yeni iş akışına taşıyın veya yeniden bağlayın.
Hangi ortamlar ve sırlar paylaşılıyor?	Ortam yönetimini spesifikasyon geçişinden ayrı planlayın.
Hangi CI işleri mevcut araçlara bağlı?	Doğrulama, test ve raporlama süreçlerini bilinçli biçimde yeniden bağlayın.

Bruno kullanıcıları için önemli nokta şudur: Git-yerel iş akışı zaten değerlidir. Spec-first Modu sözleşmeyi dosya tabanlı tutabilir; ancak Bruno varlıkları kullanım şeklinize göre ayrı geçiş, yeniden oluşturma veya değiştirme gerektirebilir.

Önerilen Geçiş Planı

Her API iş akışını aynı anda taşımaya çalışmayın. Aşamalı ilerleyin.

Aşamalı geçiş planı: Önce OpenAPI sözleşmesini taşıyın, ardından çevresindeki iş akışını yeniden bağlayın.

1. Stoplight tarzı depoyu denetleyin

Aşağıdaki dosya ve varlıkları belirleyin:

openapi.yaml
reference/
docs/
models/
.stoplight.json
toc.json
images/
postman/
bruno/
scripts/

Ayrıca CI tanımlarını, yayınlama betiklerini ve test varlıklarını da listeleyin.

2. Doğruluk kaynağını belirleyin

Git'teki OpenAPI dosyalarının sözleşme kaynağı olup olmadığını doğrulayın.

Eğer gerçek davranış Postman veya Bruno koleksiyonlarında tanımlanıyorsa, geçişten önce şu farkları çözün:

Eksik uç noktalar
Güncel olmayan örnekler
OpenAPI'de bulunmayan ortam değişkenleri
Koleksiyonlara gömülü test mantığı
Şema ve response farkları

3. Spec-first projesini oluşturun

Ekip Git'i doğruluk kaynağı olarak tutmaya hazırsa Git bağlantılı proje seçin.

Önce proje dosyalarını ve yazma deneyimini değerlendirmek istiyorsanız dosya destekli proje kullanın.

4. Aktarılan varlıkları inceleyin

Şunları kontrol edin:

OpenAPI modülleri
Endpoint grupları
Şemalar ve $ref bağımlılıkları
Markdown belgeleri
Göreceli bağlantılar
Yerel görseller
toc.json navigasyon girişleri
.stoplight.json yol ayarları
Spesifikasyonlar doğrulama sonuçları

Belirtileri arayüzde manuel olarak yamamak yerine, mümkün olduğunda kaynak proje dosyalarını düzeltin.

5. İş akışı seviyesindeki varlıkları yeniden oluşturun

Taşınan API sözleşmesi çevresinde şunları yeniden bağlayın:

Mock API'ler
Test senaryoları
İstek örnekleri
CI işleri
Raporlama
Ekip izinleri
Belge yayınlama sorumlulukları

6. İlk gerçek değişikliği yeni iş akışında çalıştırın

Küçük ancak gerçekçi bir OpenAPI değişikliği yapın.

Örnek kontrol akışı:

Bir endpoint'e yeni alan ekleyin.
Spesifikasyonu doğrulayın.
Değişikliği inceleyin.
Git bağlantısı varsa commit ve push işlemini yapın.
Belgelerin güncellendiğini kontrol edin.
İlgili mock davranışını doğrulayın.
Testleri çalıştırın.
CI raporlarını ve ekip erişimini kontrol edin.

Bu ilk değişiklik, geçişin yalnızca dosya aktarımı değil, çalışan bir iş akışı olduğunu doğrulamanın en iyi yoludur.

Bu Geçiş Yolu Ne Zaman En Uygun Olur?

Bu yaklaşım aşağıdaki durumlarda iyi bir uyum sağlar:

OpenAPI veya Swagger spesifikasyonlarını dosya olarak yönetiyorsanız
Stoplight projeniz Markdown belgeleri, modeller, görseller, .stoplight.json veya toc.json içeriyorsa
API inceleme süreciniz Git dallarına veya pull request'lere bağlıysa
Belgelerin, mock'ların, testlerin, raporların ve iş birliğinin sözleşmeye bağlı kalmasını istiyorsanız
API dosyaları ile frontend, QA, ürün, platform veya partner ekiplerinin kullandığı çalışma alanı arasındaki kaymayı azaltmak istiyorsanız

Aşağıdaki durumlarda daha fazla planlama gerekir:

Gerçek API doğruluk kaynağı OpenAPI değil, Postman veya Bruno koleksiyonlarıysa
Stoplight projesi özel yayınlama davranışlarına yoğun biçimde bağlıysa
Belgelerde çok sayıda harici bağlantı, anchor noktası, oluşturulmuş sayfa veya kullanılmayan varlık varsa
JSON Schema modelleri manuel inceleme gerektiren formatlarda tutuluyorsa
Stoplight navigasyonunun veya belge işlemenin piksel mükemmelliğinde yeniden oluşturulması bekleniyorsa

Sıkça Sorulan Sorular

Apidog Spec-first Modu bir Stoplight alternatifi mi?

OpenAPI projelerini dosya tabanlı tutarken, bu dosyalar etrafında iş birliği, test, mocklama, belge, raporlama ve izin yönetimi eklemek isteyen ekipler için Stoplight alternatifi olarak kullanılabilir.

OpenAPI spesifikasyonlarını Git'te tutabilir miyim?

Evet. Git bağlantılı bir Spec-first projesinde Git doğruluk kaynağı olmaya devam eder. Ekipler dalı senkronize edebilir, dosyaları düzenleyebilir ve değişiklikleri depoya geri commit edebilir.

Başlamak için Git'e ihtiyacım var mı?

Hayır. Git'i daha sonra bağlamak isteyen ekipler için dosya destekli Spec-first projesi kullanılabilir.

`.stoplight.json` ve `toc.json` tamamen korunur mu?

Hayır. Apidog bu dosyaların desteklenen bölümlerini geçiş girdisi olarak kullanır.

.stoplight.json temel olarak yol keşfi için kullanılır:

OpenAPI kökleri
Markdown kökleri
JSON Schema kökleri
OpenAPI dahil etme desenleri
Genel hariç tutmalar
tocPath

toc.json ise desteklenen DOCS içeriğini, OAS/modül bağlantılarını, seçili spesifikasyon öğesi bağlantılarını ve TOC referanslı model içe aktarımlarını düzenlemeye yardımcı olabilir.

Nihai belge kenar çubuğu Apidog'un DOCS/OAS/MODELLER modeliyle sınırlıdır. Bu nedenle tam Stoplight navigasyonu veya rastgele çapraz tür sıralaması korunmayabilir.

Markdown belgelerine ne olur?

Markdown belgeleri Spec-first proje iş akışına aktarılabilir. toc.json mevcutsa TOC'de listelenen belgeler desteklenen durumlarda daha fazla yapı koruyabilir.

Yine de aşağıdakileri kontrol edin:

Dahili bağlantılar
Anchor noktaları
Görseller
Göreceli yollar
Markdown işleme farkları

JSON Schema modellerine ne olur?

JSON Schema modelleri, toc.json gibi desteklenen proje yapısı tarafından açıkça referans verildiğinde desteklenen durumlarda aktarılabilir.

Bir models dizinindeki her JSON dosyasının otomatik olarak model kaynağı olacağını varsaymayın. Geçiş sonrasında şema formatını, adlarını, klasörlerini ve referanslarını inceleyin.

Görsellere ne olur?

Markdown tarafından referans verilen yerel görseller desteklenen durumlarda içe aktarılabilir.

formats.image.rootDir benzeri bir ayarı, o dizindeki her görselin içe aktarılacağı garantisi olarak değerlendirmeyin. Harici görselleri, veri URI'larını, bozuk referansları ve kullanılmayan dosyaları ayrı inceleyin.

Geçiş sonrası lint veya doğrulama çalıştırmalı mıyım?

Evet. İçe aktarılan OpenAPI dosyalarında Spesifikasyonlar doğrulamasını çalıştırın.

Apidog, Spectral tabanlı editör doğrulamasını destekleyebilir ve kök seviyedeki .spectral.yaml, .spectral.yml, .spectral.json, .spectral.mjs dosyalarını okuyabilir veya .stoplight/styleguide.json dosyasına geri dönebilir.

Sonuçları sözleşme ve stil sorunlarını bulmak için kullanın. Ancak doğrulamanın başarılı olması, Stoplight'a özgü tüm davranışların korunduğunu göstermez.

Bruno veya Postman kullanıcıları ne yapmalı?

Önce OpenAPI'nin mi yoksa koleksiyonların mı doğruluk kaynağı olduğunu belirleyin.

Spec-first geçişi OpenAPI ve ilişkili proje dosyalarına odaklanır. Koleksiyon tabanlı istek akışları, ortamlar ve testler ayrı geçiş veya yeniden oluşturma gerektirebilir.

Apidog mock'ları, testleri, CI/CD'yi, raporları ve iş birliğini destekliyor mu?

Evet. Spec-first Modu dosya tabanlı API sözleşmesini Apidog'a bağlar. Daha geniş Apidog platformu, bu sözleşme çevresinde dokümantasyon, mock'lar, test senaryoları, Apidog CLI ile CI/CD yürütme, raporlar, izinler ve ekip iş birliğini destekleyebilir.

Sonuç

Stoplight geçişi, dosya tabanlı API çalışmasından vazgeçmek anlamına gelmemelidir.

Depo doğruluk kaynağı olmaya devam edebilir. OpenAPI spesifikasyonları, Markdown belgeleri, referanslı görseller, TOC referanslı JSON Schema modelleri ve desteklenen proje yapılandırma dosyaları taşınabilir ve incelenebilir kalabilir.

Pratik geçiş yaklaşımı şudur:

Depo yapısını denetleyin.
API sözleşmesinin doğruluk kaynağını belirleyin.
Dosya tabanlı proje varlıklarını aktarın.
Stoplight'a özgü davranışları inceleyin.
Mock, test, CI, rapor ve izin iş akışlarını yeniden bağlayın.
Yeni akışta gerçek bir API değişikliği çalıştırarak doğrulayın.

Apidog Spec-first Modu, Stoplight ekipleri için bu geçişe pratik bir yol sunar: Dosya tabanlı proje bağlamını desteklenen yerlerde taşıyın, uyumluluk farklarını dikkatle inceleyin ve API sözleşmesini bağlı bir çalışma alanının merkezi haline getirin.

Kurumsal geçiş planlaması için Apidog Enterprise'a bakın.

DEV Community