Stoplight'tan Apidog'a geçiş, sadece bir OpenAPI dosyasını içe aktarmaktan ibaret değildir. Bu, dosya tabanlı bir API iş akışını dönüştürmek demektir.
Birçok ekip için Stoplight projeleri uç noktalardan fazlasını içeriyordu: Git'teki OpenAPI spesifikasyonları, Markdown belgeleri, JSON Şema modelleri, yerel görseller, desteklenen toc.json navigasyon girişleri ve desteklenen .stoplight.json yol ayarları.
Bir ekip ayrıca Postman'da istek örnekleri ve CI'da test komut dosyaları da bulundurabilir. Eğer Stoplight'tan Apidog'a geçiş yalnızca tek bir OpenAPI dosyasını içe aktarırsa, uç nokta listesi kalabilir, ancak iş akışı kaybolur.
Apidog Spec-first Modu, ekiplerin Stoplight geçişi sırasında OpenAPI dosyalarını doğruluk kaynağı olarak tutmalarına yardımcı olurken, bu dosyaları belgeler, sahte API'ler (mock'lar), testler, raporlar, izinler ve iş birliği için daha geniş bir API çalışma alanına bağlar.
Bu rehber, geçişin nasıl planlanacağını açıklar: nelerin aktarılabileceği, nelerin incelenmesi gerektiği, nelerin yeniden inşa edilmesi gerektiği ve nelerin OpenAPI sözleşmesi etrafında bağlanması gerektiği.
Operasyonel kurulum adımları 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. Stoplight tarzı bir proje genellikle bu sözleşme etrafında daha fazla bağlam içerir.
Yaygın proje varlıkları şunları içerir:
- OpenAPI veya Swagger dosyaları, genellikle
referenceveya başka bir yapılandırılmış dizin altında depolanır; - Markdown belgeleri, genellikle
docsaltında depolanır; - JSON Şema model dosyaları, genellikle
modelsaltında depolanır; - belgeler tarafından referans verilen yerel görseller;
- desteklenen yol yapılandırması için
.stoplight.json; - desteklenen belge navigasyon girişleri, gruplandırma ve sıralama için
toc.json; x-stoplight-idveyax-stoplight.idgibi Stoplight tanımlayıcıları.
Eğer geçiş yalnızca tek bir OpenAPI dosyasını içe aktarırsa, uç noktalar aktarılabilir, ancak proje modeli yine de kaybedilebilir. Belgelerin yeniden inşa edilmesi gerekebilir. Navigasyon önceki projeyle eşleşmeyebilir. Modellerin belgelerle bağlantısı kesilebilir. Testler, sahte API'ler (mock'lar) ve istek örnekleri hala ayrı araçlarda bulunabilir.
Daha iyi bir geçiş planı, tek bir spesifikasyon dosyasından değil, depodan veya dosya ağacından başlar.
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şi bu dosyalardan başlayabilir. Eğer Postman veya Bruno koleksiyonları gerçek istek iş akışını yönlendiriyorsa, öncelikle bu uyumsuzluğu çözün.
En güçlü geçiş planı "her şeyi korumak" değildir. Stoplight projeleri, başka bir çalışma alanına bire bir eşleşmeyen ürüne özgü davranışlar içerebilir.
Bunun yerine dört parçalı bir model kullanın:
| Kategori | Buraya ne ait | Geçiş duruşu |
|---|---|---|
| Aktar | OpenAPI dosyaları, desteklenen .stoplight.json yol ayarları, desteklenen toc.json navigasyon girişleri, Markdown belgeleri, referans verilen yerel görseller ve desteklendiği yerlerde JSON Şema modelleri. | Dosya tabanlı proje bağlamını Spec-first Moduna getirin. |
| İncele | Markdown bağlantıları, çapa (anchor) noktaları, görseller, TOC gruplandırması, şema adlandırması, harici $ref'ler, Stoplight Kimlikleri, oluşturulan sayfalar ve işleme farklılıkları. | Üretime hazır olarak ele almadan önce geçirilmiş çalışma alanını doğrulayın. |
| Yeniden Oluştur | Postman veya Bruno istek akışları, ortamlar, manuel testler, sahte API'ler (mock'lar), CI işleri ve yayınlama kuralları (eğer spesifikasyon projesi dışında tutuluyorsa). | Bunları OpenAPI doğruluk kaynağı etrafında yeniden oluşturun. |
| Bağla | API belgeleri, sahte API'ler (mock API'ler), testler, CI raporları, izinler, ekip iş birliği ve iş ortağına yönelik iş akışları. | Sözleşmeyi API yaşam döngüsü boyunca kullanışlı hale getirmek için Apidog'u kullanın. |
Bu ayrım önemlidir, çünkü Stoplight geçişinin iki katmanı vardır.
İlk katman dosya katmanıdır: OpenAPI spesifikasyonları, Markdown belgeleri, model dosyaları, görseller ve proje yapı dosyaları. Burası Spec-first Modu'nun en doğrudan faydalı olduğu yerdir.
İkinci katman iş akışı katmanıdır: ekibinizin API değişikliklerini nasıl incelediği, belgeleri nasıl yayınladığı, testleri nasıl çalıştırdığı, sahte API'leri (mock'ları) nasıl yönettiği, raporları nasıl paylaştığı ve arka uç, ön uç, QA, ürün ve iş ortağı ekipleri arasında nasıl iş birliği yaptığı. Bu katman, içe aktarımın bir yan ürünü olarak ele alınmamalıdır. Burası, Apidog'un sözleşmeyi API yaşam döngüsünün geri kalanına bağlayabileceği yerdir.
Apidog Spec-first Modu Stoplight Projelerine Nasıl Uyar
Apidog'un Spec-first Modu, dosya tabanlı iş akışları için inşa edilmiştir; tam da Stoplight projenizin zaten kullandığı şeydir.
Git bağlantılı projeler, deponuzu merkezde tutar. Dalınız (branch) doğruluk kaynağı olmaya devam eder ve Apidog onunla senkronize olur.
Dosya destekli projeler, önce Apidog'da doğrudan spesifikasyon dosyalarıyla çalışmanıza olanak tanır. Hazır olduğunuzda Git'i daha sonra bağlayabilirsiniz.
Spesifikasyonlar çalışma alanı, kaynak dosyalarınızı yönetmek, ayrıştırılmış API yapınızı görmek ve tüm düzenleme iş akışlarınızı yürütmek için size tek bir yer sunar.
Stoplight varlıklarının her türü Apidog'da şöyle çalışı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 adlandırmasını ve uç nokta gruplandırmasını inceleyin. |
.stoplight.json | Desteklenen alanlar, Apidog'un OpenAPI, Markdown ve JSON Şema köklerini bulmasına, OpenAPI dahil etme desenlerini, genel hariç tutma desenlerini uygulamasına ve tocPath'i çözümlemesine yardımcı olabilir. | Tam Stoplight proje yapılandırması değil, senkronizasyon için yol keşfi olarak kabul edin. Tüm Stoplight formats ayarlarının veya proje davranışının aynı şekilde uygulandığını varsaymayın. |
toc.json | Apidog'un desteklenen gruplardan ve ayırıcılardan DOCS klasörleri oluşturmasına, TOC'de listelenen Markdown belgelerini filtreleyip sıralamasına, TOC başlıklarını uygulamasına, DOCS klasörlerini içe aktarılan OAS modüllerine veya seçilen spesifikasyon öğelerine bağlamasına ve desteklendiği yerlerde TOC referanslı JSON Şema modellerini içe aktarmasına yardımcı olabilir. | İçe aktarımdan sonra son Apidog kenar çubuğunu inceleyin. Son yapı Apidog'un DOCS/OAS/MODELLER modeli aracılığıyla işlendiği için, tam Stoplight navigasyonu veya rastgele çapraz tip sıralama korunmayabilir. |
| Markdown belgeleri | Markdown belgeleri proje iş akışına aktarılabilir. TOC'de listelenen belgeler, desteklendiği yerlerde daha fazla yapıyı koruyabilir. | Dahili bağlantıları, çapa (anchor) noktalarını, biçimlendirmeyi, eksik dosyaları ve işleme farklılıklarını inceleyin. |
| Yerel görseller | Markdown tarafından referans verilen yerel görseller, desteklendiği yerlerde içe aktarılabilir. | Bozuk referansları, harici görselleri, veri URI'larını ve belgeler tarafından referans verilmeyen görselleri inceleyin. Görsel kök ayarlarını bir varlık-kütüphane içe aktarma garantisi olarak değerlendirmeyin. |
| JSON Şema modelleri | toc.json gibi desteklenen proje yapısı tarafından açıkça referans verilen JSON Şema dosyaları, desteklendiği yerlerde Modellere aktarılabilir. | Şema biçimini, adlandırmayı, gruplandırmayı, referansları ve her modelin içe aktarılıp aktırılmaması gerektiğini inceleyin. |
| Stoplight Kimlikleri | Kök seviyesindeki Stoplight Kimlikleri, Apidog'un senkronizasyonlar arasında içe aktarılan modülleri eşleştirmesine yardımcı olabilir. | Uç nokta seviyesindeki veya sayfa seviyesindeki kimliğin tamamen korunduğunu varsaymayın. |
Stoplight Proje Dosyaları İçin Uyumluluk Notları
.stoplight.json, senkronizasyon için desteklenen bir yol yapılandırma alt kümesi olarak ele alınmalıdır. Apidog, OpenAPI, Markdown ve JSON Şema için desteklenen kök dizinleri, OpenAPI dahil etme desenlerini, genel hariç tutma desenlerini vetocPath'i kullanabilir. Diğer Stoplight proje ayarları, doğrulanmadıkça yoksayıldı olarak ele alınmalıdır.toc.json, Apidog'da desteklenen navigasyon semantiklerini yeniden oluşturmaya yardımcı olabilir; buna DOCS klasörleri, Markdown sıralaması, OAS/modül bağlantıları, seçilen spesifikasyon öğesi bağlantıları ve TOC referanslı model içe aktarımları dahildir. Son kenar çubuğu hala Apidog'un DOCS/OAS/MODELLER modeli aracılığıyla işlendiği için, rastgele Stoplight düzenleri ve tam çapraz tip sıralama korunmayabilir.toc.json, son çevrimiçi belge kenar çubuğunu tam olarak özelleştirmez.- Görseller öncelikle Markdown tarafından referans verildiğinde taşınır. Referans verilmeyen varlıklar, harici görseller ve veri URI'ları ayrı olarak incelenmelidir.
- JSON Şema dosyaları, yalnızca bir dizinden varsayılmak yerine,
toc.jsongibi desteklenen proje yapısı tarafından açıkça referans verildiğinde en öngörülebilir durumdadır.
Bu, ekiplere pratik bir başlangıç noktası sunar: mümkün olduğunca API çalışma alanını yeniden oluşturmak için mevcut proje dosyalarını kullanın, ardından Stoplight'a özgü davranışa bağlı kısımları inceleyin. Amaç, Stoplight'ı piksel piksel yeniden oluşturmak değil, taşınabilir dosya tabanlı proje bağlamını korumak ve onu daha geniş bir API yaşam döngüsüne yeniden bağlamaktır.
Dosya İçe Aktarımından Bağlı API İş Akışına
Geleneksel bir içe aktarım iş akışında, ekipler genellikle bir OpenAPI dosyasını bir kez içe aktarır ve ardından yeni araçta görsel olarak çalışmaya devam ederler. Bu durum kaymaya neden olabilir: Git'teki dosya, belgeler ve API çalışma alanı artık aynı doğruluk kaynağını temsil etmeyebilir.
Spec-first Modu farklıdır. Dosyalar temel olmaya devam eder.
Git bağlantılı bir Spec-first projesinde, ekipler Spesifikasyonlar çalışma alanında dosyaları düzenleyebilir, ardından değişiklikleri taahhüt edip depoya geri gönderebilir. Dosya destekli bir projede, ekipler Git'i bağlamadan önce Apidog içinde spesifikasyon dosyalarını düzenleyebilir ve kaydedebilir.
Pratik ayrım şöyledir:
| Sorumluluk | Önerilen kaynak |
|---|---|
| API sözleşmesi | OpenAPI / Swagger dosyaları |
| Proje dosya yapısı | Depo veya dosya destekli proje ağacı |
| Desteklenen Stoplight tarzı yol ayarları | .stoplight.json |
| Desteklenen belge navigasyon girişleri | toc.json ve Markdown belgeleri |
| Günlük API iş birliği | Apidog proje çalışma alanı |
| Mock'lar, testler, raporlar ve ekip izinleri | Daha geniş Apidog platformu iş akışı |
Bu, temel geçiş değeridir: ekipler dosya öncelikli bir sözleşme modelini sürdürebilirken, daha fazla paydaşa bu sözleşme etrafında kullanılabilir bir API çalışma alanı sunar.
Veri taşımakla bir iş akışını taşımak arasındaki fark budur. Bir dosya içe aktarmak sözleşmeyi bir kez taşır. Bir Spec-first projesi bağlamak ekibe sözleşme etrafında bir çalışma alanı sunar.
Git Bağlantılı ve Dosya Destekli Geçiş Yolları
Stoplight ekipleri hepsi aynı iş akışı olgunluğundan başlamaz.
Bazı ekipler her API değişikliğini Git dalları ve çekme istekleri aracılığıyla zaten inceler. Diğerleri ise API spesifikasyonlarına ve belgelerine dosya olarak sahiptir, ancak harici bir Git sağlayıcısını ilk dağıtımın bir parçası yapmaya henüz hazır değildir.
Apidog Spec-first Modu her iki yolu da destekler.
| Yol | En uygun | Tipik iş akışı |
|---|---|---|
| Git bağlantılı Spec-first projesi | OpenAPI spesifikasyonlarını Git'te zaten yöneten ekipler için. | Depoyu bağlayın, dalı senkronize edin, dosyaları düzenleyin, taahhüt edin ve itin. |
| Dosya destekli Spec-first projesi | Git'i bağlamadan önce dosya tabanlı API tasarımı yapmak isteyen ekipler için. | Apidog'da spesifikasyon dosyalarıyla çalışın, değişiklikleri kaydedin ve önce iş akışını doğrulayın. |
Çoğu Stoplight geçişi için, Git bağlantılı projeler daha net bir uzun vadeli modeldir, çünkü depo sözleşmenin doğruluk kaynağı olmaya devam eder.
Dosya destekli projeler, ekibin yazma deneyimini değerlendirmek, proje dosyalarını temizlemek veya daha katı bir Git iş akışını benimsemeden önce geçişi aşamalandırmak istediği durumlarda faydalıdır.
Geçiş Sonrası Neler İncelenmeli
Proje dosyaları aktarılabilse bile, geçiş bir inceleme turunu içermelidir. Bu, büyük belge siteleri, çok sayıda şema dosyası veya özelleştirilmiş Stoplight navigasyonu olan ekipler için özellikle önemlidir.
Spec-first projesini oluşturduktan sonra bu kontrol listesini kullanın.
| Alan | Ne kontrol edilmeli |
|---|---|
| OpenAPI modülleri | Tüm hedeflenen 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ırıldığını onaylayın. |
| Harici referanslar | $ref bağımlılıklarının beklendiği gibi çözülüp çözülmediğini ve herhangi bir dönüştürme sorunu bildirilip bildirilmediğini kontrol edin. |
| Lint / doğrulama | İçe aktarılan OpenAPI dosyaları üzerinde Apidog Spesifikasyonlar doğrulamasını çalıştırın. Apidog, kök seviyesindeki .spectral.yaml, .spectral.yml, .spectral.json, .spectral.mjs kullanabilir ve Spectral tabanlı editör doğrulaması için .stoplight/styleguide.json'a geri dönebilir. Bulguları inceleme sinyalleri olarak ele alın, tam Stoplight stil rehberi yönetimi geçişi olarak değil. |
.stoplight.json | Desteklenen OpenAPI, Markdown ve JSON Şema köklerini, OpenAPI dahil etme desenlerini, genel hariç tutma desenlerini ve tocPath'i onaylayın. Her Stoplight yapılandırma alanının uygulandığını varsaymak yerine gerçek içe aktarım çıktısını onaylayın. |
toc.json | Desteklenen grupları, ayırıcıları, başlıkları, Markdown filtreleme ve sıralamasını, tıklanabilir grupları, OAS/modül bağlantılarını, seçilen spesifikasyon öğesi bağlantılarını, TOC referanslı model içe aktarımlarını ve nihai Apidog kenar çubuğu çıktısını inceleyin. |
| Markdown belgeleri | Biçimlendirmeyi, başlıkları, göreceli bağlantıları, çapa (anchor) noktalarını ve API dosyalarına veya işlemlerine bağlantıları kontrol edin. |
| Görseller | Yerel referanslı görsellerin doğru şekilde işlendiğini onaylayın. Harici görselleri, veri URI'larını, bozuk referansları ve kullanılmayan varlıkları ayrı olarak inceleyin. |
| Modeller | Hangi toc.json referanslı JSON Şema dosyalarının model kaynağı haline geldiğini ve adların, klasörlerin ve referansların doğru olup olmadığını onaylayın. |
| Stoplight Kimlikleri | Tekrarlanan senkronizasyonlarda modül eşleşmesinin beklendiği gibi davrandığını onaylayın. Her kaynak türü için yalnızca kimliklere güvenmeyin. |
| Testler ve mock'lar | Daha önce Postman, Bruno, CI veya ayrı araçlarda yönetilen senaryoları yeniden oluşturun veya yeniden bağlayın. |
| İzinler ve yayınlama | Yeni çalışma alanında ekip erişimini, belge görünürlüğünü, inceleme kurallarını ve yayınlama sorumluluklarını yeniden oluşturun. |
Bu inceleme bir geçici çözüm değildir. Bu, dosyaları taşımakla tüm ürüne özgü bir deneyimi taşımak arasındaki normal farktır.
Postman ve Bruno Varlıkları Hakkında Ne Olmalı?
Birçok Stoplight ekibi Postman veya Bruno da kullanır. Bu varlıklar, OpenAPI geçişinden ayrı olarak planlanmalıdır.
OpenAPI dosyaları API sözleşmesini tanımlar. Postman koleksiyonları ve Bruno .bru dosyaları genellikle istek iş akışlarını, örnekleri, ortamları veya testleri tanımlar. Değerli olabilirler, ancak Stoplight tarzı bir OpenAPI projesiyle aynı geçiş nesnesi değillerdir.
Geçişten önce ş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 hala önemli? | Önemli örnekleri bağlı API çalışma alanı etrafında yeniden oluşturun. |
| Hangi testlerin çalışmaya devam etmesi gerekir? | API testlerini belgelerle birlikte geçeceğini varsaymak yerine 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ğrulamayı, testi ve raporlamayı bilinçli olarak yeniden bağlayın. |
Bruno kullanıcıları için temel içgörü, Git-yerel iş akışının zaten değerli olmasıdır. Spec-first Modu sözleşmeyi dosya tabanlı tutabilir, ancak Bruno varlıkları, ekibin bunları nasıl kullandığına bağlı olarak yine de ayrı geçiş, yeniden inşa veya değiştirme gerektirebilir.
Önerilen Geçiş Planı
Her API iş akışını aynı anda taşımaya çalışmak yerine aşamalı bir plan kullanın.
Aşamalı bir geçiş planı: önce OpenAPI sözleşmesini taşıyın, ardından çevreleyen iş akışını yeniden bağlayın.
1. Stoplight tarzı depoyu denetleyin
OpenAPI dosyalarını, .stoplight.json, toc.json, Markdown belgelerini, modelleri, görselleri ve ilgili istek veya test varlıklarını belirleyin.
2. Doğruluk kaynağını belirleyin
Git'teki OpenAPI dosyalarının sözleşme kaynağı olup olmadığını onaylayın. Eğer başka bir araç veya koleksiyon etkili bir şekilde doğruluk kaynağı ise, geçişten önce bunu çözün.
3. Spec-first projesini oluşturun
Ekip Git'i doğruluk kaynağı olarak tutmaya hazırsa Git bağlantılı bir proje seçin. Ekip önce dosya iş akışını doğrulamak istiyorsa dosya destekli bir proje seçin.
4. Aktarılanları inceleyin
Modülleri, belgeleri, modelleri, referanslı görselleri, bağlantıları, desteklenen toc.json navigasyon girişlerini, desteklenen .stoplight.json yol ayarlarını ve Spesifikasyonlar doğrulama sonuçlarını kontrol edin. Belirtileri manuel olarak yamalamak yerine mümkün olduğunda proje dosyalarını düzeltin.
5. İş akışı seviyesindeki varlıkları yeniden oluşturun
Mock'ları, testleri, istek örneklerini, CI işlerini, raporları, izinleri ve yayınlama sorumluluklarını taşınan API sözleşmesi etrafında yeniden bağlayın.
6. İlk gerçek değişikliği yeni iş akışı üzerinden çalıştırın
Küçük bir OpenAPI değişikliği yapın, inceleyin, senkronize edin, gerekirse belgeleri güncelleyin ve alt akış mock'ları, testler ve raporların beklendiği gibi davrandığını doğrulayın.
Ekibiniz zaten OpenAPI dosyalarını, Markdown belgelerini ve şema modellerini Stoplight tarzı bir depoda yönetiyorsa, Apidog Spec-first Modu, tam iş akışını yeniden oluşturmadan önce geçiş yolunu test etmenize yardımcı olabilir.
Bu Geçiş Yolu Ne Zaman En Uygun Olur
Bu geçiş yolu, aşağıdaki durumlarda iyi bir uyum sağlar:
- ekibiniz OpenAPI veya Swagger spesifikasyonlarını dosya olarak yönetiyorsa;
- Stoplight projeniz Markdown belgeleri, modeller, görseller,
.stoplight.jsonveyatoc.jsoniçeriyorsa; - API inceleme süreciniz zaten Git dallarına veya çekme isteklerine bağlıysa;
- API belgelerinin, mock'ların, testlerin, raporların ve iş birliğinin sözleşmeye bağlı kalmasını istiyorsanız;
- API dosyaları ile ön uç, QA, ürün, platform veya iş ortağı ekipleri tarafından kullanılan çalışma alanı arasındaki kaymayı azaltmak istiyorsanız.
Aşağıdaki durumlarda daha fazla planlama gerektirebilir:
- gerçek API doğruluk kaynağı OpenAPI yerine bir Postman veya Bruno koleksiyonuysa;
- Stoplight projesi özel yayınlama davranışına yoğun bir şekilde dayanıyorsa;
- belgeler çok sayıda harici bağlantı, çapa (anchor) noktası, oluşturulmuş sayfa veya referans verilmeyen varlık içeriyorsa;
- JSON Şema modelleri, manuel inceleme gerektiren biçimlerde veya yapılarla depolanıyorsa;
- ekip, Stoplight navigasyonunun veya belge işlenmesinin piksel mükemmelliğinde bir yeniden oluşturulmasını istiyorsa.
Sıkça Sorulan Sorular
Apidog Spec-first Modu bir Stoplight alternatifi mi?
OpenAPI projelerini dosya tabanlı tutarken, bu dosyalar etrafında daha geniş API iş birliği, test, mocklama, belge, raporlama ve izin yönetimi eklemek isteyen ekipler için bir Stoplight alternatifi olarak kullanılabilir.
OpenAPI spesifikasyonlarını Git'te tutabilir miyim?
Evet. Git bağlantılı bir Spec-first projesinde ekipler, Git'i doğruluk kaynağı olarak tutabilir, bir dalı senkronize edebilir, dosyaları düzenleyebilir ve değişiklikleri depoya geri taahhüt edebilir.
Başlamak için Git'e ihtiyacım var mı?
Hayır. Ekip önce spesifikasyon dosyalarıyla çalışmak ve Git'i daha sonra bağlamak istediğinde dosya destekli bir Spec-first projesi kullanılabilir.
.stoplight.json ve toc.json tamamen korunuyor mu?
Hayır. Apidog, bu dosyaların desteklenen kısımlarını geçiş girişleri olarak kullanır. .stoplight.json esas olarak senkronizasyon sırasında yol keşfi için kullanılır; desteklenen OpenAPI, Markdown, JSON Şema kökleri, OpenAPI dahil etme desenleri, genel hariç tutmalar ve tocPath dahil. toc.json, desteklenen DOCS içeriğini, OAS/modül bağlantılarını, seçilen spesifikasyon öğesi bağlantılarını ve TOC referanslı model içe aktarımlarını düzenlemeye yardımcı olabilir. Son çevrimiçi belge kenar çubuğu hala Apidog'un DOCS/OAS/MODELLER modeli tarafından kısıtlanır, bu nedenle tam Stoplight navigasyonu ve rastgele çapraz tip sıralama korunmayabilir.
Markdown belgelerine ne olur?
Markdown belgeleri Spec-first proje iş akışına aktarılabilir. toc.json mevcut olduğunda, TOC'de listelenen belgeler desteklendiği yerlerde yapılarını daha fazla koruyabilir. Dahili bağlantılar, çapa (anchor) noktaları, görseller ve işleme hala incelenmelidir.
JSON Şema modellerine ne olur?
JSON Şema modelleri, toc.json gibi desteklenen proje yapısı tarafından açıkça referans verildiğinde, desteklendiği yerlerde aktarılabilir. Bir modeller dizini altındaki her JSON dosyasının otomatik olarak bir model kaynağı olacağını varsaymayın. Geçişten sonra şema biçimini, adlarını, klasörlerini ve referanslarını inceleyin.
Görsellere ne olur?
Markdown tarafından referans verilen yerel görseller, desteklendiği yerlerde içe aktarılabilir. formats.image.rootDir'i, o dizindeki her görsel dosyasının içe aktarılacağına dair bir garanti olarak değerlendirmeyin. Harici görseller, veri URI'ları, bozuk referanslar ve kullanılmayan görsel dosyaları ayrı olarak kontrol edilmelidir.
Geçiş sonrası lint veya doğrulama çalıştırmalı mıyım?
Evet. Geçiş sonrası, içe aktarılan OpenAPI dosyaları üzerinde Spesifikasyonlar doğrulamasını çalıştırın. Apidog, Spectral tabanlı düzenleyici doğrulamasını destekler ve kök seviyesindeki .spectral.yaml, .spectral.yml, .spectral.json, .spectral.mjs dosyalarını okuyabilir veya .stoplight/styleguide.json'a geri dönebilir. Sonuçları sözleşme ve stil sorunlarını incelemek için kullanın; doğrulama başarısını, Stoplight'a özgü her davranışın korunduğuna dair bir kanıt olarak kabul etmeyin.
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 ilgili proje dosyalarına odaklanır. Koleksiyon tabanlı istek iş akışları, ortamlar ve testler ayrı geçiş veya yeniden inşa gerektirebilir.
Apidog ayrıca 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 ve daha geniş Apidog platformu, o sözleşme etrafında belgelemeyi, mock'ları, test senaryolarını, Apidog CLI ile CI/CD yürütmeyi, raporları, izinleri 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 Şema modelleri ve desteklenen proje yapı dosyaları taşınabilir ve incelenebilir kalabilir. Aynı zamanda, bu dosyalar etrafındaki API iş akışı daha bağlantılı hale gelebilir.
Apidog Spec-first Modu, Stoplight ekiplerine pratik bir geçiş yolu sunar: projenin dosya tabanlı kısımlarını desteklendiği yerlerde aktarın, Stoplight'a özgü yapıyı dikkatlice inceleyin ve bağlı bir API çalışma alanı etrafında iş akışı seviyesindeki varlıkları yeniden oluşturun.
Ekibiniz bir Stoplight geçişini değerlendiriyorsa, depo yapınızı denetleyerek ve API sözleşmesini hangi dosyaların tanımladığına karar vererek başlayın. Ardından bu dosyaları Apidog'da belgelere, mock'lara, testlere, raporlara, izinlere ve iş birliğine bağlamak için Spec-first Modunu kullanın.
Kurumsal geçiş planlaması için Apidog Enterprise'a bakın.