Stoplight Studio veya Stoplight Platform'dan Apidog'a geçiş yapıyorsanız, bilmeniz gereken ilk şey OpenAPI belirtimlerinizi yeniden yüklemenize gerek olmadığıdır. Apidog'un Spec-First Modu (şu anda beta aşamasında), mevcut GitHub veya GitLab deponuza doğrudan bağlanır, böylece Git, doğruluk kaynağı olarak kalır ve commit geçmişiniz bozulmadan korunur. Bu kılavuz her adımı açıklar: Stoplight yapılandırmanızı dışa aktarma, dizin kurallarını Apidog'un beklentilerine göre eşleme ve .stoplight.json ile toc.json dosyalarını Apidog eşdeğerleriyle değiştirme.
Dünya Ekonomik Forumu'ndaki gibi ekipler, belgeler için Stoplight'ın yanı sıra OpenAPI belirtimlerini zaten Git'te yönetiyor. Kurulumunuz bu tanıma uyuyorsa, bu kılavuz sizin için yazılmıştır. Ve eğer bir geçişe kesin olarak karar vermek yerine seçenekleri hala değerlendiriyorsanız, en iyi Stoplight Studio alternatifleri yazısı daha geniş bir perspektif sunmaktadır.
Geçiş yaptığınızda ne aynı kalır
OpenAPI dosyalarınız, Git deponuz ve dal stratejiniz değişmez. Temel öncül budur. Stoplight, belirtimleri sürüm kontrolüne kaydedilmiş YAML veya JSON dosyaları olarak depolar. Apidog, bir depoyu Spec-First Modu'nda bağladığınızda aynı dosyaları okur.
Değişen şey, üzerine eklenen her şeydir: dokümantasyon oluşturucu, sahte sunucu, test çalıştırıcı ve API istemcisi. Stoplight Platform'un belgeleri sunması ve Postman'ın testleri ayrı bir araç olarak yürütmesi yerine, Apidog tüm bunları mühendislerinizin zaten commit ettiği aynı OpenAPI dosyasına senkronize ederek tek bir çalışma alanında birleştirir.
Pratik sonuç: geçişiniz çoğunlukla bir veri geçişi değil, bir yapılandırma değişimidir.
Adım 1: Stoplight proje varlıklarınızı dışa aktarın
Apidog'a dokunmadan önce, Stoplight'ın Git'te olmayan her şeyi yakalayın.
Stoplight Studio'yu bir Git arka ucuyla kullanıyorsanız:
OpenAPI belirtimleriniz, JSON Schema modelleriniz ve Markdown dokümantasyonunuz zaten kaydedilmiştir. Yerel kopyanızın güncel olduğundan emin olmak için bir git pull çalıştırın. Stoplight, OpenAPI Şartnamesi formatını takip eder ve bu belirtim dosyaları Apidog'da dönüştürmeye gerek kalmadan çalışır. Depo yapınız muhtemelen şöyle görünecektir:
your-api-repo/
.stoplight.json # Proje yapılandırması (değiştirilmesi gerekiyor)
reference/
petstore.yaml # OpenAPI belirtiminiz/belirtimleriniz
models/
error.json # Paylaşılan JSON Şema modelleri
docs/
introduction.md # Markdown kılavuz sayfaları
authentication.md
toc.json # İçindekiler tablosu sırası (değiştirilmesi gerekiyor)
assets/
images/
architecture.png
Stoplight Platform'u kullanıyorsanız (bulut tabanlı, Git arka ucu yok):
Belirtimlerinizi Stoplight kullanıcı arayüzünden dışa aktarın: her bir API projesini açın, “Dışa Aktar” seçeneğine gidin ve OpenAPI YAML dosyasını indirin. Markdown belgeleri için, bunları yeni bir Git deposundaki docs/ klasörüne kopyalayın. Stoplight, Git tabanlı olmayan projeler için toplu dışa aktarma sunmadığından, bunu her API projesi için ayrı ayrı yapın.
Dosyalarınız bir Git deposunda (GitHub veya GitLab) olduğunda, bir sonraki adıma geçin.
Adım 2: Değiştirdiğiniz yapılandırma dosyalarını anlayın
İki Stoplight'a özgü dosya proje yapısını belirler. İkisinin de Apidog'da doğrudan bir karşılığı yoktur, ancak ne işe yaradıklarını anlamak, Apidog'da neyi yapılandırmanız gerektiğini size tam olarak söyler.
| Stoplight dosyası | Ne işe yarar | Apidog karşılığı |
|---|---|---|
.stoplight.json |
Proje kökünü, belirtim yollarını, belge yollarını ve projeye dahil edilen dosyaları belirtir | Apidog projesi içindeki depo bağlantı ayarları (bir dosya değil, kullanıcı arayüzü aracılığıyla yapılandırılır) |
toc.json |
Stoplight belge kenar çubuğundaki sayfaların sırasını ve gruplandırmasını kontrol eder | Apidog dizin yapısını okur; kenar çubuğu sırası düz bir dosya yerine Apidog belge düzenleyicisinde ayarlanır |
reference/ kuralı |
Stoplight'ın OpenAPI belirtim dosyalarını beklediği yer | Apidog Spec-First Modu'nda yapılandırılabilir; varsayılan olarak depo köküne ayarlanmıştır, ancak onu reference/ öğesine yönlendirebilirsiniz |
models/ kuralı |
Paylaşılan bileşenler için JSON Şema dosyaları | Bunları OpenAPI belirtiminizin components/schemas bölümünden referans alın; Apidog $ref yollarını çözer |
docs/ kuralı |
Markdown kılavuz sayfaları | Apidog'a dokümantasyon sayfaları olarak içe aktarın; dizin hiyerarşisi kenar çubuğu bölümlerine eşlenir |
Anahtar bilgi: .stoplight.json ve toc.json Stoplight'a özgüdür. Bunları depoda bırakabilirsiniz (Apidog bilinmeyen dosyaları yok sayar), ancak Apidog'da hiçbir şeyi yönlendirmeyeceklerdir. Eşdeğer ayarları Apidog proje kullanıcı arayüzü aracılığıyla yapılandırırsınız.
Adım 3: Deponuzu Apidog Spec-First Modu'na bağlayın
Apidog Spec-First Modu, bir GitHub veya GitLab deposunu bir Apidog projesine bağlayarak OpenAPI belirtiminin her zaman Git'ten okunmasını, dahili bir Apidog veritabanından değil, sağlamanın yoludur. Bu, Git'i yetkili kaynak olarak tutar ve mühendislerinizin belirtimi güncellemek için bugün yaptıkları gibi PR'lar göndermeye devam edebilecekleri anlamına gelir.
İşte bağlantı akışı. OAuth izin onayı konusunda emin değilseniz, GitHub'ın üçüncü taraf uygulamaları depolara bağlama belgelerini de inceleyebilirsiniz.
- Apidog'da yeni bir proje **Spec-First Modu** oluşturun.
- Apidog'u GitHub veya GitLab hesabınızla doğrulayın ve depoyu seçin.
3. **Dal**ı ayarlayın: üretim belirtimleri için varsayılan dalınızı (main veya master) veya geçiş testi sırasında bir özellik dalını kullanın.
- Kaydedin. Apidog belirtimi okur ve bundan etkileşimli dokümantasyonu, sahte sunucu uç noktalarını ve test altyapısını oluşturur.
Belirtiminiz, models/ dizininden şemaları çekmek için $ref kullanıyorsa, Apidog bu referansları belirtim dosyasının konumuna göre çözer. OpenAPI dosyanızdaki yollar doğru olduğu sürece ek yapılandırmaya gerek yoktur. Bu Git senkronizasyonunun nasıl çalıştığına dair daha derinlemesine bir bakış için, OpenAPI belirtimini GitHub ile senkronize etme kılavuzu mekaniği ayrıntılı olarak ele alır.
Adım 4: Markdown dokümantasyonunuzu taşıyın
Stoplight, Markdown kılavuz sayfalarını API referans belgeleriyle tek bir kenar çubuğunda karıştırmanıza olanak tanır. Apidog da aynısını dokümantasyon düzenleyicisi aracılığıyla yapar.
Deponuzu bağladıktan sonra, docs/ Markdown dosyalarınızı içe aktarın:
- Apidog projesinde, **Belgeler** bölümünü açın.
- **İçe Aktar > Markdown** seçeneğini kullanarak dosyalarınızı yükleyin veya içeriği sayfa sayfa yapıştırın.
Markdown'ınızda referans verilen görsel varlıklar (tipik bir Stoplight düzeninde assets/images/ klasörü) için, bunları Apidog'un dosya depolama alanına yükleyin ve her sayfadaki  referanslarını güncelleyin. Görselleriniz zaten bir CDN'de veya herkese açık bir URL'de barındırılıyorsa, hiçbir şeyi değiştirmenize gerek yoktur.
Adım 5: Stoplight'ın sahte sunucusunu değiştirin
Stoplight Studio, OpenAPI belirtiminizi okuyan ve örnek yanıtlar döndüren yerel bir sahte sunucu içerir. Apidog'un sahte sunucusu da aynısını yapar, ancak bulut tabanlıdır ve yerel bir işlem çalıştırmaya gerek kalmadan tüm ekibinize erişilebilir.
Belirtiminiz Spec-First Modu aracılığıyla bağlandığında, Apidog, OpenAPI dosyanızda tanımlanan her işlem için otomatik olarak sahte uç noktalar oluşturur. Örnek yanıtlar, belirtiminizdeki examples alanından veya hiçbir örnek tanımlanmamışsa Apidog'un akıllı sahte motorundan gelir. Belirtim dosyasına dokunmadan Apidog içinde uç nokta başına yanıt kurallarını geçersiz kılabilirsiniz.
Yerel olarak stoplight mock reference/your-api.yaml çalıştırmaya alışkın bir ekip için, değişiklik, QA mühendislerinizin ve frontend geliştiricilerinizin artık paylaşılan bir bulut URL'sine ulaşmasıdır. Ağ erişim politikalarınıza uyduğunu doğrulamak için bunu bir denemede test etmeye değerdir.
Adım 6: Test paketlerinizi yeniden oluşturun
Stoplight'ın sözleşme testini veya lintleme için Spectral kurallarını kullandıysanız, bunlar ayrı bir işlem gerektirir.
Spectral lint kuralları: Stoplight, OpenAPI lintlemesi için Spectral'ı kullanır ve bu, bir .spectral.yaml dosyası aracılığıyla yapılandırılır. Apidog'un OpenAPI uyumluluğu için kendi yerleşik lint kuralları vardır, ancak Spectral'ı doğrudan çalıştırmaz. Ekibinizin güvendiği özel Spectral kurallarınız varsa, bunları Apidog'dan bağımsız olarak CI'da (GitHub Actions veya GitLab CI) çalıştırmaya devam edin. Apidog'un lint kapsamı ve özel lint kural kümelerini projeler arasında paylaşıp paylaşamayacağınız, belirli kural gereksinimlerinize göre bir denemede doğrulamaya değerdir.
API testleri: Stoplight Platform senaryo tabanlı API testi içerir. Apidog'un test çalıştırıcısı, test senaryolarını görsel olarak oluşturmanıza, istekleri zincirlemenize ve yanıt gövdesi, başlıklar ve durum kodlarına karşı iddiaları çalıştırmanıza olanak tanır. Bunları Apidog içinde yeniden oluşturacaksınız; Stoplight test projelerinden otomatik içe aktarma yoktur. Git-native API iş akışı kılavuzu, Apidog test çalıştırmalarını bir GitHub Actions pipeline'ına nasıl entegre edeceğinizi gösterir.
Çalışan bir örnek: Stoplight testiniz POST /orders isteğinin bir location başlığıyla birlikte 201 döndürdüğünü doğruladıysa, işte Apidog CLI kullanarak bir CI pipeline'ındaki eşdeğer Apidog test kurulumu:
# .github/workflows/api-tests.yml
name: API sözleşme testleri
on:
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Apidog testlerini çalıştır
run: |
npx apidog-cli run \
--project-id ${{ secrets.APIDOG_PROJECT_ID }} \
--test-id ${{ secrets.APIDOG_TEST_SUITE_ID }} \
--env production \
--reporter junit \
--output test-results.xml
env:
APIDOG_API_KEY: ${{ secrets.APIDOG_API_KEY }}
- name: Test sonuçlarını yayınla
uses: mikepenz/action-junit-report@v4
if: always()
with:
report_paths: test-results.xml
Bu, CI'daki bir Stoplight test çalıştırmasının yerini alır ve mevcut GitHub Actions yapınızı bozulmadan korur.
Kurumsal ekipler için değerlendirme kontrol listesi
Daha büyük bir ekip için (Studio yerine Stoplight Platform'u değerlendiren türden) geçiş yapıyorsanız, taahhütte bulunmadan önce doğrulanması gereken belirli yetenekler vardır. Apidog bu alanları kapsar, ancak kesin davranış planınıza ve çalışma alanı yapılandırmanıza bağlıdır.
| Yetenek | Bir Apidog denemesinde neyi doğrulamanız gerekir |
|---|---|
| Özel dokümantasyon erişimi | Belge sayfalarını kimliği doğrulanmış kullanıcılarla veya belirli e-posta alan adlarıyla kısıtlayabilir misiniz? Erişim kontrolü gereksinimlerinize göre kontrol edin. |
| Projeler arasında şema/bileşen yeniden kullanımı | Paylaşılan bir components/schemas kütüphanesi, kopyala-yapıştır yapmadan birden fazla Apidog projesinden referans alınabilir mi? Gerçek şema dosyalarınızla test etmeye değer. |
| Özel lint kuralı paylaşımı | Aynı çalışma alanındaki birden fazla Apidog projesinde paylaşılan bir lint profilini (paylaşılan bir .spectral.yaml'ye eşdeğer) dağıtabilir misiniz? |
| SSO/SCIM sağlama | Apidog'un SSO'su kimlik sağlayıcınızı destekliyor mu? SCIM sağlama ayrıntısının kullanıcı yaşam döngüsü yönetimi sürecinize uyduğunu doğrulayın. |
| Denetim günlükleri | Denetim günlüğü hangi olayları ve hangi formatta yakalar? Uyum veya güvenlik inceleme gereksinimlerinizi karşıladığını doğrulayın. |
Bunları engelleyici faktörler olarak değil, değerlendirme görevleri olarak çerçeveleyin. Çoğu, temsili bir proje ile iki haftalık bir deneme süresince doğrulanabilir.
Sıkça Sorulan Sorular
Spectral'ı Apidog ile kullanmaya devam edebilir miyim?
Evet. Spectral'ı CI pipeline'ınızda Apidog'dan bağımsız olarak çalıştırın. .spectral.yaml dosyanız depoda kalır ve CI işiniz (GitHub Actions, GitLab CI) her PR'da OpenAPI dosyasını lintler. Apidog dokümantasyon, sahteleme ve test işlemlerini yürütür; Spectral lintlemeyi yapar. Çatışmazlar. CI entegrasyon seçenekleri için Spectral'ın dokümantasyonuna bakın.
Depoyu Apidog'a bağladığımda $ref yollarım bozulur mu?
Yollarınız belirtim dosyasında doğruysa bozulmaz. Apidog, $ref öğesini kök OpenAPI dosyasının konumuna göre çözer. Belirtiminiz $ref: '../models/error.json' diyorsa ve models/ klasörü reference/ klasörünün bir üst düzeyindeyse, Apidog depodaki o göreceli yolu takip eder. Önce harici referanslar kullanan bir belirtimle test edin.
Apidog Spec-First Modu GitHub'ı olduğu gibi GitLab'ı da destekliyor mu?
Evet, hem GitHub hem de GitLab desteklenmektedir. Bağlantı akışı aynıdır; GitLab hesabınızla doğrulama yapar ve depoyu ve dalı seçersiniz. Sürüm kontrolü seçenekleri hakkında daha fazla bilgi için, Git ile OpenAPI sürüm kontrolü kılavuzu dal stratejilerini ayrıntılı olarak ele alır.
Geçişten sonra mevcut Stoplight belge URL'ime ne olur?
Stoplight'ta barındırılan dokümantasyon URL'leri (docs.stoplight.io/your-org/your-api), Stoplight aboneliğinizi iptal ettiğinizde çalışmayı durdurur. Apidog, belgelerinize yapılandırdığınız bir alt alan adında yeni bir URL verir. Stoplight belge sayfalarınıza işaret eden harici bağlantılarınız varsa, DNS veya CDN katmanında yönlendirmeler ayarlayın.
.stoplight.json ve toc.json dosyalarını depodan silmem gerekiyor mu?
Hayır. Apidog tanımadığı dosyaları yok sayar. Bunları kaldırmak birleştirme çakışmalarına veya karışıklığa neden olacaksa yerlerinde bırakın. Ekip tamamen Apidog'a geçtiğinde, bunları bir temizlik PR'ında silebilirsiniz, ancak geçişin çalışması için bu gerekli değildir.
Sonuç
Stoplight'tan Apidog'a geçiş, sıfırdan başlamak anlamına gelmez. OpenAPI belirtimleriniz Git'te kalır, dal iş akışınız bozulmadan devam eder ve reference/, models/ ve docs/ dizin yapınız Apidog'un beklediğiyle temiz bir şekilde eşleşir. Geçiş bir yapılandırma değişimidir: .stoplight.json ve toc.json dosyalarını Apidog proje ayarlarıyla değiştirin, deponuzu Spec-First Modu aracılığıyla bağlayın ve test senaryolarınızı Apidog'un test çalıştırıcısı içinde yeniden oluşturun.
Mevcut GitHub veya GitLab OpenAPI deponuzu Apidog Spec-First Modu'na bağlayarak Stoplight geçişinize başlayın. Yeniden yükleme yok, kilitlenme yok, aynı Git geçmişi. Başlamak için Apidog'u indirin ve yukarıdaki değerlendirme kontrol listesini gerçek verilerinizle çalışmak için denemeniz için temsili bir API projesi kullanın.